Shared repository implementation that normalizes options and delegates
data operations to a DataSource.
-
coerceId(id: Id): EntityKey
Cast the entity id to the type the adapter expects.
-
count(options?: CountOptions): Promise<number>
Count entities with optional filtering.
-
create(data: Partial<Entity>): Promise<Entity>
Insert a new entity.
-
delete(id: Id): Promise<boolean>
Delete an entity by primary key.
-
exists(id: Id): Promise<boolean>
Check whether an entity with the given primary key exists.
-
findAll(options?: FindOptions): Promise<Entity[]>
Fetch entities with optional filtering, sorting, and pagination.
-
findById(id: Id): Promise<Entity | null>
Fetch a single entity by its primary key.
-
findOne(options?: FindOptions): Promise<Entity | null>
Find the first entity that matches the supplied query options.
-
findPage(options: PageOptions): Promise<Page<Entity>>
Find a page of entities by cursor pagination.
-
toEntity(row: Partial<Record<string, unknown>>): Entity
Cast a raw row to the typed Entity.
-
update(): Promise<Entity>id: Id,data: Partial<Entity>
Update an existing entity by primary key.
The Bigtable adapter.
-
beginTransaction(options?: TransactionOptions): Promise<IAdapterTransaction>
Opens a single-row deferred-write transaction.
-
connect(): Promise<void>
Resolves the client and the instance handle.
-
createDataSource(entity: string): IDataSource
Returns a data source for the named entity's table. @inheritdoc
-
disconnect(): Promise<void>
Releases the client.
-
isReady(): boolean
Reports whether the adapter is connected. @inheritdoc
-
rawQuery<T>(): Promise<T[]>_sql: string,_params?: unknown[]
Refuses the raw query by name.
-
transactionIsolationLevels: readonly TransactionIsolationLevel[]
Bigtable exposes no portable transaction-isolation selector.
Thrown when a Bigtable transaction is asked to write a second row.
-
name: string
Discriminant for consumers that cannot use
instanceofacross realms.
The Cosmos adapter — an Azure Cosmos DB NoSQL-API backend.
-
beginTransaction(options?: TransactionOptions): Promise<IAdapterTransaction>
Opens a deferred-write transaction whose buffer is flushed as one transactional batch at commit.
-
connect(): Promise<void>
Establishes the connection: resolves the client and proves the database is reachable with these credentials.
-
createDataSource(entity: string): IDataSource
Returns a data source for the named entity's container. @inheritdoc
-
disconnect(): Promise<void>
Releases the client and the per-container caches.
-
isReady(): boolean
Reports whether the adapter is connected. @inheritdoc
-
rawQuery<T>(): Promise<T[]>_sql: string,_params?: unknown[]
Refuses the raw query by name.
-
transactionIsolationLevels: readonly TransactionIsolationLevel[]
Cosmos DB exposes no portable transaction-isolation selector.
Thrown when a Cosmos update loses an optimistic-concurrency race.
-
name: string
Discriminant for consumers that cannot use
instanceofacross realms.
Thrown when a Cosmos transaction is asked to do something a transactional batch cannot express.
-
name: string
Discriminant for consumers that cannot use
instanceofacross realms.
Database service implementation wrapping an ORM adapter.
- close(): Promise<void>
-
getRepository<Entity, Id extends EntityKey = string>(entity: string): IRepository<Entity, Id>
Returns a repository bound to the named entity on the outer database scope.
-
isClosed(): boolean
Reports whether
closehas run — a LIFECYCLE-only read that reaches no adapter and performs no I/O (M90b). - isHealthy(): Promise<boolean>
- migrate(): Promise<void>
-
query<T>(): Promise<T[]>sql: string,params?: unknown[]
-
transaction<T>(): Promise<T>work: (uow: IUnitOfWork) => Promise<T>,options?: TransactionOptions
Drizzle adapter wrapping a Drizzle database instance.
- beginTransaction(options?: TransactionOptions): Promise<IAdapterTransaction>
- connect(): Promise<void>
- createDataSource(entity: string): DataSource
-
createDataSourceForEntity(entity: string): DataSource
Create a DataSource for the named entity using the main instance.
- disconnect(): Promise<void>
- isReady(): boolean
-
rawQuery<T>(): Promise<T[]>sql: string,params?: unknown[]
-
transactionIsolationLevels(): readonly TransactionIsolationLevel[]
The branded transaction bridge either accepts every portable level or no isolation request at all; it is the application's explicit guarantee.
Repository backed by the Drizzle adapter.
The DynamoDB adapter — a key-value store backend served through the portable data-access contract.
-
beginTransaction(options?: TransactionOptions): Promise<IAdapterTransaction>
Opens a deferred transaction: an empty buffer shared by every data source created from the returned handle. Commit flushes the buffer as one
TransactWriteItemscall; rollback discards it and sends nothing. -
connect(): Promise<void>
Establishes the adapter's client, resolving the injected or lazy loader.
-
createDataSource(entity: string): IDataSource
Returns a data source for the named entity's table. @inheritdoc
-
disconnect(): Promise<void>
Destroys the client the adapter constructed and releases it. An injected client is released without
destroy(): it belongs to the application, which may reuse it. -
isReady(): boolean
Reports whether the adapter resolved a client. @inheritdoc
-
rawQuery<T>(): Promise<T[]>_sql: string,_params?: unknown[]
Refuses the raw SQL query by name — DynamoDB has no SQL — rather than emulating it (the silent-divergence defect M70j closed). The error names the adapter and points at the client for native commands.
-
transactionIsolationLevels: readonly TransactionIsolationLevel[]
DynamoDB exposes no portable transaction-isolation selector.
In-memory implementation of IDatabaseAdapter.
- beginTransaction(options?: TransactionOptions): Promise<IAdapterTransaction>
- connect(): Promise<void>
-
countEntities(): Promise<number>entity: string,where: Record<string, unknown>,filter?: FilterExpression
Count entities matching a filter.
-
createDataSource(): DataSourceentity: string,primaryKey?: string | readonly string[]
-
deleteEntity(): Promise<boolean>entity: string,id: EntityKey
Delete an entity by primary key.
- disconnect(): Promise<void>
-
findEntityById(): Promise<Record<string, unknown> | null>entity: string,id: EntityKey
Find a single entity by its primary key value.
-
findPageInternal(): Promise<PageResult>entity: string,query: NormalizedQuery,getRecords: () => Record<string, unknown>[]
Core
findPageimplementation shared between the non-transactional data source and the transaction overlay. ThegetRecordsthunk lets the two callers — the committed store and the per-tx overlay — each supply their visible row set without duplicating the cursor-handling logic. -
getStore(): EntityStoreentity: string,primaryKey?: string | readonly string[]
Returns the internal store for an entity, creating it lazily.
-
insertEntity(): Promise<Record<string, unknown>>entity: string,data: Partial<Record<string, unknown>>
Insert a new entity. Generates key values if absent.
- isReady(): boolean
-
queryEntities(): Promise<Record<string, unknown>[]>entity: string,query: NormalizedQuery
Query entities with full filtering, sorting, and pagination.
-
rawQuery<T>(): Promise<T[]>_sql: string,_params?: unknown[]
-
transactionIsolationLevels: readonly TransactionIsolationLevel[]
Portable isolation levels this adapter can honestly provide.
-
updateEntity(): Promise<Record<string, unknown>>entity: string,id: EntityKey,data: Partial<Record<string, unknown>>
Update an existing entity by primary key, merging fields.
The Mongo adapter — a document-store backend over the native driver.
-
assertConnected(): void
Asserts the adapter is connected before a data operation.
-
beginTransaction(options?: TransactionOptions): Promise<IAdapterTransaction>
Opens a driver session and calls
startTransaction(). A deployment without a replica set fails here, with the driver's own error wrapped inMongoTransactionUnavailableError— never atconnect(). -
connect(): Promise<void>
Establishes the database connection, resolving the client and database name.
-
createDataSource(entity: string): import("@setu-ts/common").IDataSource
Returns a data source for the named entity's collection. @inheritdoc
-
disconnect(): Promise<void>
Closes the connection and releases the client. @inheritdoc
-
isReady(): boolean
Reports whether the adapter is connected. @inheritdoc
-
rawQuery<T>(): Promise<T[]>_sql: string,_params?: unknown[]
Refuses the raw SQL query by name — MongoDB has no SQL — rather than emulating it (the silent-divergence defect M70j closed). The error names the adapter and points at the injected client for native commands.
-
transactionIsolationLevels: readonly TransactionIsolationLevel[]
MongoDB snapshot isolation is not the portable serializable guarantee.
Prisma adapter wrapping the official Prisma client.
- beginTransaction(options?: TransactionOptions): Promise<IAdapterTransaction>
- connect(): Promise<void>
- createDataSource(entity: string): DataSource
-
createDataSourceForEntity(entity: string): DataSource
Create a DataSource for the named entity using the main client.
- disconnect(): Promise<void>
- isReady(): boolean
-
rawQuery<T>(): Promise<T[]>sql: string,params?: unknown[]
-
transactionIsolationLevels(): readonly TransactionIsolationLevel[]
Portable levels available from the resolved Prisma connector.
Repository backed by the Prisma adapter.
Thrown when the database rejected a write because a concurrent transaction changed the same data (X38-1, M90f). The operation did not happen and may be retried.
-
name: string
Discriminant for consumers that cannot use
instanceofacross realms.
Concrete Unit of Work that holds a transaction and delegates repository creation to the database service within the transaction boundary.
-
commit(): Promise<void>
Commit the transaction. Must be called after all operations complete.
- getRepository<Entity, Id extends EntityKey = string>(entity: string): IRepository<Entity, Id>
-
rollback(): Promise<void>
Roll back the transaction. Called automatically by
DatabaseServiceon errors, but can also be called explicitly.
Thrown at translation time when a filter operator cannot be honoured by the active backend with the connector in use.
-
connector: string | undefined
The connector the operator failed on, or
undefinedwhen the connector could not be determined.'sqlite'names the concrete refusal;undefinedmeans the adapter could not identify its connector and theprovideroption is the fix. -
name: string
Discriminant for consumers that cannot use
instanceofacross realms. -
operator: string
The filter operator that could not be translated (e.g.
'contains').
Thrown when a database adapter cannot honour a requested transaction isolation level.
-
name: string
Discriminant for consumers that cannot use
instanceofacross realms.
Thrown by IDatabaseService.migrate because programmatic
migrations are not implemented by the current adapters.
-
name: string
Discriminant for consumers that cannot use
instanceofacross realms.
Thrown when an adapter refuses a query feature that is expressible in the
portable IDataSource contract but not supported by the active
backend.
-
adapter: string
The adapter name (e.g.
'prisma','drizzle','memory'). -
feature: string
The query feature that could not be honoured (e.g.
'composite-key'). -
name: string
Discriminant for consumers that cannot use
instanceofacross realms.
Thrown by MongoAdapter.rawQuery — MongoDB has no SQL, so a raw
query is refused by name rather than emulated (the silent-divergence defect
M70j closed). The error names the adapter and points at the injected client
for native commands.
-
adapter: string
The adapter name that refused the raw query (e.g.
'mongodb'). -
name: string
Discriminant for consumers that cannot use
instanceofacross realms.
Creates the opaque configuration required by the Drizzle adapter and query accessors.
Creates a DataSource backed by a Drizzle instance for the given
entity name.
Creates the no-import arm of the client seam.
Creates the no-import arm of the DynamoDB client seam.
Creates the lazy SDK loader.
Creates the lazy DynamoDB SDK loader.
Creates a DataSource backed by a Prisma client for the given
entity name.
Creates the DatabasePlugin.
Decode a cursor token to its CursorPayload, or null when the
token is malformed.
Encode a CursorPayload as a base64url-encoded JSON token.
Returns the exact configured outer Drizzle database for a database service.
Returns Drizzle's callback-scoped transaction object for a Unit of Work.
Build the "row after this one" keyset comparison as a portable
FilterExpression.
Declares that an application-owned Drizzle bridge forwards transaction options to its driver.
The options both BigtableAdapterOptions arms share.
-
instance: string
The Bigtable instance the tables live in. Required on both arms: a table is addressed as
project/instance/table, and neither an injected client nor a project id encodes the instance. -
maxPageFetches: number
How many server round trips one
findPagemay take before it returns a bounded — but explicitly non-terminal — page. Defaults to10. -
tables: Readonly<Record<string, BigtableEntityMapping>>
Per-entity table, row-key, column and value-encoding overrides, keyed by the entity name passed to
getRepository().
One stored cell: the raw value bytes, as text.
-
value: string
The cell value, as the text the adapter's value codec wrote.
Client construction settings consumed by the lazy SDK arm.
-
apiEndpoint: string
An explicit API endpoint, such as
127.0.0.1:8086forcbtemulator. -
projectId: string
The GCP project the instance lives in.
The deferred client-resolution seam the adapter lifecycle drives.
-
load(): Promise<IBigtableClient>
Resolves a client without forcing the injected arm through an SDK import.
-
owned: boolean
Whether the loader constructed the client itself.
The 'bigtable' arm — a Google Cloud Bigtable wide-column backend.
-
options: BigtableAdapterOptions
Bigtable adapter configuration;
instanceand one client form are required. -
type: "bigtable"
Selects the Bigtable arm.
How one entity name maps onto a physical Bigtable table.
-
columnFamily: string
The column family unmapped fields are written to. Defaults to
'cf'. -
columns: Readonly<Record<string, string>>
Per-field column addresses. A value of
'family'keeps the field name as the qualifier;'family:qualifier'names both. -
rowKey: BigtableRowKeyMapping
How the row key is composed. Defaults to
{ fields: ['id'] }. -
table: string
The table id. Defaults to the entity name itself.
-
valueEncoding: BigtableValueEncoding
How values round-trip through a cell. Defaults to
'tagged'.
What a read asks the server for.
-
filter: BigtableFilter
A server-side filter applied to every candidate row.
-
keys: readonly string[]
An explicit key list. A key with no row contributes no result.
-
limit: number
A server-side row cap. Omitted means unbounded.
-
ranges: readonly BigtableRowRange[]
Row-key ranges, unioned.
One row as a read returns it.
-
data: BigtableRowData
The row's cells.
-
key: string
The row key.
One end of a row-key range.
-
inclusive: boolean
Whether the boundary row itself is included.
-
value: string
The boundary row key.
How an entity's logical fields compose its single row key.
-
fields: readonly string[]
The logical fields the row key is composed from, in order. The order is load-bearing: it is both the byte order the key sorts in and the order the portable cursor carries key values in.
-
prefix: string
A constant prefix prepended to every row key of this entity.
-
separator: string
The separator joining the fields. Defaults to
'#'. Ignored for a single-field key, which is the field's own string form.
A row-key range. An omitted end is unbounded in that direction.
-
end: BigtableRowBoundary
The upper bound, or unbounded when omitted.
-
start: BigtableRowBoundary
The lower bound, or unbounded when omitted.
An exact byte range a cell value must fall in.
-
end: string
The inclusive upper bound.
-
start: string
The inclusive lower bound.
One access condition — the optimistic-concurrency guard the replace path uses.
-
condition: string
The
_etagthe write is conditional on. -
type: "IfMatch"
The condition kind; the adapter only ever sends
IfMatch.
The options both CosmosAdapterOptions arms share — everything
that is required or optional regardless of how the client is supplied.
-
containers: Readonly<Record<string, CosmosEntityMapping>>
Per-entity container, primary-key and partition-key overrides, keyed by the entity name passed to
getRepository(). -
database: string
The database the containers live in. Required on both arms: a Cosmos endpoint encodes no database name, so unlike a MongoDB URI there is nothing to fall back to.
A batch operation removing one document.
-
id: string
The document id.
-
operationType: "Delete"
The operation kind.
A batch operation inserting a whole document. The id is optional: the service mints one when the body carries none.
-
id: string
The document id, when the caller chose one.
-
operationType: "Create" | "Upsert"
The operation kind.
-
resourceBody: Record<string, unknown>
The document to write.
A batch operation carrying patch operations rather than a whole document.
-
id: string
The document id.
-
operationType: "Patch"
The operation kind.
-
resourceBody: { readonly operations: readonly CosmosPatchOperation[]; }
The patch operations, in the envelope the SDK expects.
A batch operation overwriting a whole document, which therefore names the document it replaces.
-
id: string
The document id.
-
operationType: "Replace"
The operation kind.
-
resourceBody: Record<string, unknown>
The document to write in its place.
The response a transactional batch answers with.
-
code: number
The overall status code;
200when every operation succeeded. -
result: readonly { readonly statusCode: number; }[]
The per-operation results, in the order the operations were sent.
The container definition the partition-key resolver reads.
-
partitionKey: { readonly paths?: readonly string[]; readonly kind?: string; }
The partition-key definition, present on every container.
The arm selecting the Cosmos adapter over the @azure/cosmos SDK — Azure
Cosmos DB's NoSQL (SQL) API.
-
options: CosmosAdapterOptions
Cosmos adapter configuration;
databaseand one credential form are required. -
type: "cosmos"
Selects the Cosmos arm.
How one entity name maps onto a physical Cosmos container.
-
container: string
The container name. Defaults to the entity name itself, so
getRepository('orders')needs no mapping at all. -
partitionKey: string | readonly string[] | readonly (readonly string[])[]
The document field path(s) carrying the partition key.
-
primaryKey: string
The repository-visible primary-key field name. Defaults to
'id'.
The response envelope every single-item operation answers with.
-
resource: T
The resource, or
undefinedwhen none was returned. -
statusCode: number
The HTTP status code.
One JSON-patch-shaped operation. The adapter only emits set, and only for
top-level fields, so the "cannot create a path whose parent is absent"
limitation measured on the SDK is unreachable through it.
-
op: "set"
The operation kind.
-
path: string
The document path, always a single leading-slash segment.
-
value: unknown
The value to set.
One named query parameter. Values are always bound rather than interpolated, so a value can never be read as SQL.
-
name: string
The parameter name, including its leading
@. -
value: unknown
The bound value.
A parameterized Cosmos SQL query — the shape items.query accepts.
-
parameters: readonly CosmosQueryParameter[]
The bound parameters.
-
query: string
The SQL text, with
@nameplaceholders for every value.
Per-request options the adapter passes to a single-item operation.
-
accessCondition: CosmosAccessCondition
The optimistic-concurrency guard, when the write is conditional.
Options for IRepository.count.
-
filter: FilterExpression
Portable filter expression conjoined with
where. -
where: Record<string, unknown>
Filter conditions applied to the count query.
The decoded contents of a cursor minted by encodeCursor: the
values of every ordered field (in orderBy order) plus the primary-key
column values (for tiebreaker lookups) plus a stable fingerprint of the
sort specification. The fingerprint is what a fingerprint mismatch on decode
detects.
-
keyValues: ReadonlyArray<CursorValue>
The primary-key column values (in key-column order), from the row the cursor was minted against. Used by
keysetPredicateas the tiebreaker fallback when a key column is absent fromorderBy. -
orderedValues: ReadonlyArray<CursorValue>
The value of every ordered field (in
orderBydeclaration order), from the row the cursor was minted against. Indexiis the value of the i-th entry ofObject.entries(orderBy). -
sortFingerprint: string
A stable fingerprint of the resolved sort specification: each ordered field paired with its direction, in order. A cursor minted under one sort and presented under another has a different fingerprint, so the caller is refused by name rather than served a silently wrong page.
The arm supplying an externally-implemented backend.
-
adapter: IDatabaseAdapter
The backend to use, already constructed. The plugin calls
connect()on it duringregister()anddisconnect()during shutdown; it never constructs or replaces it. -
type: "custom"
Selects the external-adapter arm.
Adapter-specific configuration passed to the database adapter.
-
drizzleInstance: DrizzleDatabaseIdentity
Inject the application's opaque configured Drizzle database, created by
createDrizzleDatabase(database, transactionBridge). Required whentype: 'drizzle'— seeDrizzleAdapterOptions, which makes that a compile error rather than a startup throw. The explicit bridge positively guarantees Promise-aware native callback semantics instead of inferring them from a structural transaction method. -
drizzleTables: Record<string, unknown>
Registry mapping entity name → a real Drizzle table definition. Required when
type: 'drizzle'— seeDrizzleAdapterOptions, which makes that a compile error rather than a startup throw. -
logQueries: boolean
When
true, log SQL queries to the registered logger. -
prismaClient: unknown
Inject an application-generated Prisma v7 client. This is required for the Prisma adapter because generated-client output belongs to the application rather than this package — see
PrismaAdapterOptions, which makes that a compile error rather than a startup throw. -
provider: PrismaSqlProvider
The SQL connector the injected Prisma client is bound to.
-
transactionTimeout: number
Timeout (ms) for Prisma interactive transactions. Defaults to 30_000. Prisma's default is ~5s which is too short for a full Unit of Work.
-
url: string
Database connection URL (e.g.,
postgresql://localhost:5432/mydb).
The options every DatabasePluginOptions arm shares.
-
name: string
Named connection for multi-database support. Defaults to
'default'. -
options: DatabaseAdapterOptions
Adapter-specific options.
A point-in-time reading of the database driver's connection-pool counters (M90b).
-
idle: number
Connections currently idle in the pool.
-
total: number
Total connections the pool holds (idle + in use).
-
waiting: number
Callers currently waiting for a connection.
DatabaseAdapterOptions narrowed for the Drizzle arm: the
configured instance and the table registry are both required.
-
dialect: SqlJsonDialect
The SQL dialect, used only to translate a nested JSON filter path (
field: ['profile', 'city']). No two dialects spell JSON extraction alike: PostgreSQL uses#>>, MySQLJSON_UNQUOTE(JSON_EXTRACT(...))and SQLitejson_extract. -
drizzleInstance: DrizzleDatabaseIdentity
The opaque configuration returned by
createDrizzleDatabase(database, transactionBridge). Required. -
drizzleTables: Record<string, unknown>
Entity name → real Drizzle table definition. Required, and must hold at least one entry.
-
entities: Readonly<Record<string, DrizzleCompositeKeyOptions>>
Per-entity overrides keyed by the entity name passed to
IRepository.getRepository. -
poolStats: () => DatabasePoolCapacity
Application-owned callback reporting the driver's connection-pool counters (M90b). The application reads its own driver's documented pool API — the configured Drizzle identity is opaque to this package — and the adapter publishes the returned
DatabasePoolCapacitysnapshot to thedatabasehealth indicator through an internal seam.
Per-entity overrides for the Drizzle adapter.
-
primaryKey: string | readonly string[]
Primary-key column(s) for this entity.
Opaque configuration for one exact Drizzle database and async transaction bridge.
Erased identity of a package-created Drizzle configuration.
The arm selecting the Drizzle adapter.
-
options: DrizzleAdapterOptions
Drizzle adapter configuration; the instance and table registry are required.
-
type: "drizzle"
Selects the Drizzle arm.
The options both DynamoAdapterOptions arms share — everything
that is optional regardless of how the client is supplied.
-
entities: Readonly<Record<string, DynamoEntityMapping>>
Per-entity table and key mappings, keyed by the entity name passed to
getRepository(). -
maxPageFetches: number
The maximum number of server pages one
findPagecall fetches while filling the page, defaulting to 10.
A DynamoDB attribute value in the subset the adapter reads and writes.
-
B: Uint8Array
A binary value.
-
BOOL: boolean
A boolean value.
-
BS: readonly Uint8Array[]
A set of binary values.
-
L: readonly DynamoAttributeValue[]
An ordered list of attribute values.
-
M: DynamoAttributeMap
A nested map value.
-
N: string
A base-10 number encoded as text.
-
NS: readonly string[]
A set of base-10 numbers encoded as text.
-
NULL: boolean
A DynamoDB null marker.
-
S: string
A UTF-8 string value.
-
SS: readonly string[]
A set of string values.
AWS client construction settings consumed by the lazy SDK arm.
-
credentials: unknown
AWS credentials or an SDK-supported credential provider.
-
endpoint: string
An optional custom endpoint, such as DynamoDB Local.
-
region: string
The AWS region supplied to
DynamoDBClient.
The deferred client-resolution seam used by the adapter lifecycle.
-
load(): Promise<IDynamoClient>
Resolves a client without forcing the injected arm through an SDK import.
A conditional expression used to prevent an unintended write.
-
ConditionExpression: string
A DynamoDB condition expression, including attribute-existence guards.
The arm selecting the DynamoDB adapter over the AWS SDK v3 client.
-
options: DynamoAdapterOptions
DynamoDB adapter configuration;
region(orclient) is required. -
type: "dynamodb"
Selects the DynamoDB arm.
Input for DynamoDB DeleteItem.
-
Key: DynamoAttributeMap
The complete primary key.
-
ReturnValues: "ALL_OLD"
Requests the prior row so deletion can report whether it existed.
-
TableName: string
The physical table to write.
Output from DynamoDB DeleteItem.
-
Attributes: DynamoAttributeMap
The deleted row when one existed and
ALL_OLDwas requested.
How one entity name maps onto a physical DynamoDB table.
-
dateAttributes: Readonly<Record<string, DynamoDateEncoding>>
The encoding each date-bearing attribute is stored under.
-
indexes: Readonly<Record<string, DynamoIndexMapping>>
The table's configured global secondary indexes, keyed by index name.
-
partitionKey: string
The table's partition-key attribute.
-
sortKey: string
The table's sort-key attribute, when the table is keyed by partition AND sort.
-
table: string
The table name. Defaults to the entity name itself, so
getRepository('users')needs no mapping at all.
Expression aliases shared by all command shapes.
-
ExpressionAttributeNames: Readonly<Record<string, string>>
Generated
#namealiases mapped to physical attribute names. -
ExpressionAttributeValues: DynamoAttributeMap
Generated
:valuealiases mapped to DynamoDB values.
Input for DynamoDB GetItem.
-
Key: DynamoAttributeMap
The complete primary key.
-
ProjectionExpression: string
A projection expression for selected attributes.
-
TableName: string
The physical table to read.
Output from DynamoDB GetItem.
-
Item: DynamoAttributeMap
The item, omitted when no item matches the key.
A configured global secondary index and its key schema.
-
partitionKey: string
The index's partition-key attribute.
-
sortKey: string
The index's sort-key attribute, when the index carries one.
Input for DynamoDB PutItem.
-
Item: DynamoAttributeMap
The complete item to persist.
-
TableName: string
The physical table to write.
Output from DynamoDB PutItem.
-
Attributes: DynamoAttributeMap
Returned attributes when the command asks for them.
Input for DynamoDB Query.
-
IndexName: string
An optional configured global secondary index.
-
KeyConditionExpression: string
The required partition-key condition, optionally with a sort condition.
-
ScanIndexForward: boolean
truefor ascending sort-key order andfalsefor descending.
Shared fields for a DynamoDB query or scan.
-
ExclusiveStartKey: DynamoAttributeMap
The server continuation key from the preceding response.
-
FilterExpression: string
A post-read filter expression.
-
Limit: number
The maximum number of evaluated items.
-
ProjectionExpression: string
A projection expression for selected attributes.
-
Select: "ALL_ATTRIBUTES"
| "ALL_PROJECTED_ATTRIBUTES"
| "COUNT"
| "SPECIFIC_ATTRIBUTES"The response shape requested from DynamoDB.
-
TableName: string
The physical table to read.
The common DynamoDB Query and Scan response shape.
-
Count: number
Number of returned or counted items in this response.
-
Items: readonly DynamoAttributeMap[]
Returned items, omitted by
Select: 'COUNT'. -
LastEvaluatedKey: DynamoAttributeMap
The authoritative server continuation key, when further results exist.
-
ScannedCount: number
Number of items DynamoDB evaluated before filtering.
The native DynamoDB SDK client operations driven by the facade.
-
destroy(): void
Releases resources owned by the AWS SDK client.
-
send<TInput, TOutput>(command: DynamoSdkCommand<TInput, TOutput>): Promise<TOutput>
Sends one DynamoDB command to the configured AWS endpoint.
A native DynamoDB SDK command accepted by DynamoSdkClient.
-
input: TInput
The command request supplied to the AWS SDK.
-
output: TOutput
The typed AWS SDK response, when a command carries one.
The native @aws-sdk/client-dynamodb module shape adapted by the lazy arm.
-
DeleteItemCommand: DynamoCommandConstructor<>DynamoDeleteItemCommandInput,DynamoDeleteItemCommandOutput
The AWS
DeleteItemCommandconstructor. -
DynamoDBClient: new (configuration: DynamoClientConfiguration) => DynamoSdkClient
The AWS DynamoDB client constructor.
-
GetItemCommand: DynamoCommandConstructor<DynamoGetItemCommandInput, DynamoGetItemCommandOutput>
The AWS
GetItemCommandconstructor. -
PutItemCommand: DynamoCommandConstructor<DynamoPutItemCommandInput, DynamoPutItemCommandOutput>
The AWS
PutItemCommandconstructor. -
QueryCommand: DynamoCommandConstructor<DynamoQueryCommandInput, DynamoReadCommandOutput>
The AWS
QueryCommandconstructor. -
ScanCommand: DynamoCommandConstructor<DynamoScanCommandInput, DynamoReadCommandOutput>
The AWS
ScanCommandconstructor. -
TransactWriteItemsCommand: DynamoCommandConstructor<>DynamoTransactWriteItemsCommandInput,DynamoTransactWriteItemsCommandOutput
The AWS
TransactWriteItemsCommandconstructor. -
UpdateItemCommand: DynamoCommandConstructor<>DynamoUpdateItemCommandInput,DynamoUpdateItemCommandOutput
The AWS
UpdateItemCommandconstructor.
A transactional Delete operation.
-
Key: DynamoAttributeMap
The complete primary key.
-
TableName: string
The physical table to write.
A transactional Put operation.
-
Item: DynamoAttributeMap
The complete item to persist.
-
TableName: string
The physical table to write.
A transactional Update operation.
-
Key: DynamoAttributeMap
The complete primary key.
-
TableName: string
The physical table to write.
-
UpdateExpression: string
The update expression to apply.
One transaction operation accepted by DynamoDB TransactWriteItems.
-
Delete: DynamoTransactDelete
A conditional delete operation.
-
Put: DynamoTransactPut
A conditional create operation.
-
Update: DynamoTransactUpdate
A conditional update operation.
Input for DynamoDB TransactWriteItems.
-
TransactItems: readonly DynamoTransactWriteItem[]
The ordered writes that DynamoDB commits atomically.
Input for DynamoDB UpdateItem.
-
Key: DynamoAttributeMap
The complete primary key.
-
ReturnValues: "ALL_NEW"
Requests the persisted row after a successful update.
-
TableName: string
The physical table to write.
-
UpdateExpression: string
The update expression to apply.
Output from DynamoDB UpdateItem.
-
Attributes: DynamoAttributeMap
The persisted row when
ReturnValuesisALL_NEW.
Options for IRepository.findAll.
-
cursor: string
A keyset cursor position, or
undefinedwhen the query starts at the first page. Carried alongsideoffsetrather than replacing it: an offset says "skip this many from the start" and a cursor says "after this row", and the two are contradictory — a query carrying both is refused by name (UnsupportedQueryFeatureError). -
filter: FilterExpression
Portable filter expression conjoined with
where. -
limit: number
Maximum number of results to return.
-
offset: number
Number of results to skip.
-
orderBy: Record<string, OrderDirection>
Field-to-direction sort specification.
-
select: readonly string[]
Select only specific fields (projection).
-
where: Record<string, unknown>
Filter conditions keyed by field name.
A transaction handle that can also open entity data sources bound to itself.
-
createDataSource(entity: string): IDataSource
Open a data source for
entitybound to THIS transaction.
The Bigtable client the adapter drives.
-
close(): Promise<void>
Releases the client's gRPC channels.
-
instance(id: string): IBigtableInstance
Returns a handle for one instance. No RPC is issued.
One Bigtable instance.
-
table(id: string): IBigtableTable
Returns a handle for one table. No RPC is issued.
The row-scoped write surface: one atomic check-and-mutate.
-
conditionalMutate(): Promise<boolean>test: readonly BigtableFilter[],branches: { readonly onMatch?: readonly BigtableMutation[]; readonly onNoMatch?: readonly BigtableMutation[]; }
Applies one branch of a CheckAndMutateRow atomically.
One table's data-plane surface.
-
readRows(options: BigtableReadOptions): Promise<BigtableReadRow[]>
Reads rows matching the supplied key set, range set and filter.
-
row(key: string): IBigtableRow
Returns the row-scoped write surface for one key.
A structural subset of the SDK CosmosClient — the members the adapter
drives.
-
database(id: string): ICosmosDatabase
Addresses a database by id. The database is not created.
A structural subset of the SDK Container — the members the adapter drives.
-
item(): ICosmosItemid: string,partitionKey?: CosmosPartitionKeyValue
Addresses one document by id and partition key.
-
items: ICosmosItems
The document collection.
-
read(): Promise<CosmosItemResponse<CosmosContainerDefinition>>
Reads the container definition, which is also what proves the container exists.
A structural subset of the SDK Database.
-
container(id: string): ICosmosContainer
Addresses a container by id. The container is not created.
-
read(): Promise<CosmosItemResponse<Record<string, unknown>>>
Reads the database, proving the credentials and the database name.
A structural subset of the SDK Item handle — one document addressed by its
id and partition key.
-
delete(): Promise<CosmosItemResponse<Record<string, unknown>>>
Deletes the document, throwing a 404 when it does not exist.
-
patch(operations: readonly CosmosPatchOperation[]): Promise<CosmosItemResponse<Record<string, unknown>>>
Applies a patch to the document server-side.
-
read(): Promise<CosmosItemResponse<Record<string, unknown>>>
Reads the document.
-
replace(): Promise<CosmosItemResponse<Record<string, unknown>>>body: Record<string, unknown>,options?: CosmosRequestOptions
Replaces the document wholesale.
A structural subset of the SDK Items collection — the members the data
source drives.
-
batch(): Promise<CosmosBatchResponse>operations: readonly CosmosBatchOperation[],partitionKey: CosmosPartitionKeyValue
Runs a transactional batch, atomic within one partition-key value.
-
create(body: Record<string, unknown>): Promise<CosmosItemResponse<Record<string, unknown>>>
Inserts one document, refusing a duplicate id within the partition.
-
query(spec: CosmosQuerySpec): ICosmosQueryIterator<Record<string, unknown>>
Runs a parameterized SQL query across the container.
A query iterator, narrowed to the one member the adapter uses.
-
fetchAll(): Promise<CosmosFeedResponse<T>>
Materializes every matching row.
The full database backend port: lifecycle plus data access.
-
beginTransaction(options?: TransactionOptions): Promise<IAdapterTransaction>
Begin a transaction, returning a handle that can open transaction-scoped data sources as well as commit and roll back.
-
createDataSource(entity: string): IDataSource
Open a non-transactional data source for the named entity.
-
rawQuery<T>(): Promise<T[]>sql: string,params?: unknown[]
Execute a raw query in the backend's own dialect.
High-level database service combining repository access, unit of work, raw queries, and lifecycle management.
-
close(): Promise<void>
Gracefully close all database connections.
-
getRepository<Entity, Id extends EntityKey = string>(entity: string): IRepository<Entity, Id>
Get a repository for the named entity type.
-
isHealthy(): Promise<boolean>
Health-check probe: verifies the database connection is alive.
-
migrate(): Promise<void>
Programmatic migrations are unsupported by the current adapters. Each ORM owns schema migration through its own CLI, so this rejects with
UnsupportedMigrationError. -
query<T>(): Promise<T[]>sql: string,params?: unknown[]
Execute a raw SQL query and return results.
-
transaction<T>(): Promise<T>work: (uow: IUnitOfWork) => Promise<T>,options?: TransactionOptions
Execute the
workcallback within a database transaction.
The data-access seam a backend provides per entity.
-
count(): Promise<number>where: Record<string, unknown>,filter?: FilterExpression
Count entities matching a filter.
-
create(data: Partial<Record<string, unknown>>): Promise<Record<string, unknown>>
Insert a new entity.
-
delete(id: EntityKey): Promise<boolean>
Delete an entity by primary key.
-
findAll(query: NormalizedQuery): Promise<Record<string, unknown>[]>
Find every entity matching the normalized query.
-
findById(id: EntityKey): Promise<Record<string, unknown> | null>
Find a single entity by its primary key value.
-
findPage(query: NormalizedQuery): Promise<PageResult>
Find a page of entities by cursor pagination.
-
update(): Promise<Record<string, unknown>>id: EntityKey,data: Partial<Record<string, unknown>>
Update an existing entity by primary key.
The structural DynamoDB facade the adapter drives.
-
deleteItem(input: DynamoDeleteItemCommandInput): Promise<DynamoDeleteItemCommandOutput>
Deletes one item.
-
destroy(): void
Releases resources held by a client constructed through the lazy path.
-
getItem(input: DynamoGetItemCommandInput): Promise<DynamoGetItemCommandOutput>
Reads a single item by its complete key.
-
putItem(input: DynamoPutItemCommandInput): Promise<DynamoPutItemCommandOutput>
Creates one item.
-
query(input: DynamoQueryCommandInput): Promise<DynamoReadCommandOutput>
Sends a key-constrained query.
-
scan(input: DynamoScanCommandInput): Promise<DynamoReadCommandOutput>
Scans a table or index when no key-constrained query is possible.
-
transactWriteItems(input: DynamoTransactWriteItemsCommandInput): Promise<DynamoTransactWriteItemsCommandOutput>
Commits a bounded set of writes atomically.
-
updateItem(input: DynamoUpdateItemCommandInput): Promise<DynamoUpdateItemCommandOutput>
Updates one existing item.
A structural subset of the driver MongoClient — the members the adapter
drives.
-
close(): Promise<void>
Closes the connection.
-
connect(): Promise<void>
Opens the connection.
-
db(name: string): IMongoDatabase
Returns the database named
name. -
startSession(): IMongoSession
Starts a new session.
A structural subset of the driver Collection — the methods the data source
calls to serve the six IDataSource methods.
-
countDocuments(): Promise<number>filter: Record<string, unknown>,options?: MongoWriteOptions
Counts matching documents.
-
deleteOne(): Promise<{ deletedCount: number; }>filter: Record<string, unknown>,options?: MongoWriteOptions
Deletes matching documents.
-
find(): IMongoCursorfilter: Record<string, unknown>,options?:MongoOptions
& { sort?: Record<string, unknown>; skip?: number; limit?: number; projection?: Record<string, 0 | 1>; }Finds matching documents.
-
findOne(): Promise<Record<string, unknown> | null>filter: Record<string, unknown>,options?:MongoOptions
& { projection?: Record<string, 0 | 1>; sort?: Record<string, unknown>; }Finds a single document.
-
findOneAndUpdate(): Promise<Record<string, unknown> | null>filter: Record<string, unknown>,update: Record<string, unknown>,options: IMongoCollectionFindOneAndUpdateOptions
Finds one document and applies an update, returning the updated document.
-
insertOne(): Promise<document: Record<string, unknown>,options?: MongoWriteOptions>{ acknowledged: boolean; insertedId: IMongoObjectId | string | number; }
Inserts one document.
The native driver findOneAndUpdate options the adapter passes through.
-
returnDocument: "before" | "after"
Returns the updated document (rather than the original).
-
session: IMongoSession
The session a transaction-scoped operation runs under.
A structural subset of the driver's cursor returned from find().
-
toArray(): Promise<Record<string, unknown>[]>
Materializes the cursor's matching documents.
A structural subset of the driver Database — what the collection resolver
reads.
-
collection(name: string): IMongoCollection
Returns the collection named
name.
A structural subset of the driver ObjectId — enough for the conversion
rules the mapping owns.
-
toString(): string
Serializes the id to its 24-hex string, the value callers address.
The driver ObjectId constructor shape.
-
isValid(value: unknown): boolean
Tests whether a value is a valid
ObjectId— exactly a 24-hex string, so a 12-char value is rejected.
A structural subset of the driver ClientSession — the members the
transaction path calls.
-
abortTransaction(): Promise<void>
Rolls the active transaction back.
-
commitTransaction(): Promise<void>
Commits the active transaction.
-
endSession(): Promise<void>
Ends the session, releasing its server resources.
-
startTransaction(options?: Record<string, unknown>): Promise<void>
Starts the transaction on this session.
Generic repository providing CRUD operations over an entity type.
-
count(options?: CountOptions): Promise<number>
Count entities with optional filtering.
-
create(data: Partial<Entity>): Promise<Entity>
Insert a new entity.
-
delete(id: Id): Promise<boolean>
Delete an entity by primary key.
-
exists(id: Id): Promise<boolean>
Check whether an entity with the given primary key exists.
-
findAll(options?: FindOptions): Promise<Entity[]>
Fetch entities with optional filtering, sorting, and pagination.
-
findById(id: Id): Promise<Entity | null>
Fetch a single entity by its primary key.
-
findOne(options?: FindOptions): Promise<Entity | null>
Fetch the first entity matching the optional filter.
-
findPage(options: PageOptions): Promise<Page<Entity>>
Find a page of entities by cursor pagination.
-
update(): Promise<Entity>id: Id,data: Partial<Entity>
Update an existing entity by primary key.
Unit of Work: transaction-scoped repository access.
-
getRepository<Entity, Id extends EntityKey = string>(entity: string): IRepository<Entity, Id>
Get a transaction-scoped repository for the named entity.
The arm selecting the zero-dependency in-memory adapter, which is also what
an omitted type means.
-
type: "memory"
ORM adapter type. Defaults to
'memory'.
The options both MongoAdapterOptions arms share — everything
that is optional regardless of how the client is supplied.
-
collections: Readonly<Record<string, MongoEntityMapping>>
Per-entity collection and primary-key overrides, keyed by the entity name passed to
getRepository(). -
database: string
The database the collections live in.
-
objectIdCtor: IMongoObjectIdCtor
The driver's
ObjectIdconstructor whenMongoAdapterOptions.clientis injected.
The arm selecting the Mongo adapter over the native mongodb driver.
-
options: MongoAdapterOptions
Mongo adapter configuration;
url(orclient) is required. -
type: "mongodb"
Selects the Mongo arm.
How one entity name maps onto a physical Mongo collection.
-
collection: string
The collection name. Defaults to the entity name itself, so
getRepository('users')needs no mapping at all. -
idType: "objectId" | "raw" | "compound"
How the collection stores its
_idvalues. -
primaryKey: string | readonly string[]
The primary-key field name(s). Defaults to
'id'.
Operation options the data source passes to every driver call — the session a transaction-scoped data source binds to.
-
session: IMongoSession
The session a transaction-scoped operation runs under.
A repository query with every option resolved to a concrete value — the
shape a IDataSource evaluates.
-
cursor: string
A keyset cursor position, or
undefinedwhen the query starts at the first page. Carried alongsideoffsetrather than replacing it: an offset says "skip this many from the start" and a cursor says "after this row", and the two are contradictory — a query carrying both is refused by name (§3.10). -
filter: FilterExpression
Optional portable expression conjoined with
where. -
limit: number
Maximum results, or
-1for unlimited. -
offset: number
Number of leading rows to skip.
-
orderBy: Record<string, OrderDirection>
Field-to-direction sort specification. Empty means no ordering.
-
select: readonly string[]
Field projection. Empty means all fields.
-
where: Record<string, unknown>
Filter conditions, matched by equality. Empty means no filter.
A single page of entities returned by IRepository.findPage,
plus the cursor that continues to the next page (or null when the page
is the last).
-
nextCursor: string | null
A cursor to fetch the next page, or
nullwhen no further page exists. -
rows: Entity[]
The rows in this page, already filtered, sorted, paginated and projected.
A single page of rows returned by IDataSource.findPage, plus the
cursor that continues to the next page (or null when the page is the last).
-
nextCursor: string | null
A cursor to fetch the next page, or
nullwhen the page is the last. -
rows: Record<string, unknown>[]
The rows in this page, already filtered, sorted, paginated and projected.
DatabaseAdapterOptions narrowed for the Prisma arm: the injected
client is required.
-
entities: Readonly<Record<string, PrismaCompositeKeyOptions>>
Per-entity overrides for key resolution and other model-specific tuning.
-
prismaClient: unknown
The application-generated Prisma v7 client. Required — a framework package cannot locate an application-selected generated-client output path, and
PrismaAdapter.connect()rejects without it.
Per-entity overrides for the Prisma adapter.
-
compositeKeyName: string
Override for the derived compound-key field name.
-
keyColumns: readonly string[]
The primary-key columns for this entity, in Prisma schema declaration order.
The arm selecting the Prisma adapter.
-
options: PrismaAdapterOptions
Prisma adapter configuration;
prismaClientis required. -
type: "prisma"
Selects the Prisma arm.
Optional controls for opening a transaction.
-
isolation: TransactionIsolationLevel
Requested isolation level; omitted preserves the adapter default.
& { readonly projectId: string; readonly apiEndpoint?: string; readonly client?: IBigtableClient; }
| (
& { readonly client: IBigtableClient; readonly projectId?: string; readonly apiEndpoint?: string; }
Options for the BigtableAdapter — the 'bigtable' arm.
| { readonly method: "insert"; readonly data: Readonly<Record<string, Readonly<Record<string, string>>>>; }
One mutation in a CheckAndMutateRow branch or a batch entry.
A row's cells, addressed family → qualifier → versions.
How a value round-trips through a cell.
| PrismaDatabaseOptions
| DrizzleDatabaseOptions
| MongoDatabaseOptions
| DynamoDatabaseOptions
| CosmosDatabaseOptions
| BigtableDatabaseOptions
The arm selecting one of the adapters this package ships.
& { readonly endpoint: string; readonly key: string; readonly client?: ICosmosClient; }
| (
& { readonly client: ICosmosClient; readonly endpoint?: string; readonly key?: string; }
Options for the CosmosAdapter — the 'cosmos' arm.
| CosmosBatchReplaceOperation
| CosmosBatchPatchOperation
| CosmosBatchDeleteOperation
One operation in a transactional batch.
| number
| boolean
| null
| readonly (string | number | boolean | null)[]
A partition-key value as Cosmos accepts it: a JSON scalar, or an array of
them for a hierarchical (MultiHash) partition key.
A scalar value retained by a portable keyset cursor.
Options for the DatabasePlugin factory.
The native transaction object supplied by a configured Drizzle database.
Promise-aware transaction bridge owned by the application at configuration.
& { readonly region: string; readonly endpoint?: string; readonly credentials?: unknown; readonly client?: IDynamoClient; }
| (
& { readonly client: IDynamoClient; readonly region?: string; readonly endpoint?: string; readonly credentials?: unknown; }
Options for the DynamoAdapter — the 'dynamodb' arm.
A DynamoDB item or key map.
A native DynamoDB SDK command constructor.
The storage encoding a date-bearing attribute is declared to use.
Input for DynamoDB Scan.
Output from DynamoDB TransactWriteItems.
A primary key value: a scalar string, a scalar number, or a composite
key expressed as a readonly record of named columns to values.
| { readonly type: "comparison"; readonly field: string | readonly string[]; readonly operator: "contains"; readonly value: string; }
| { readonly type: "comparison"; readonly field: string | readonly string[]; readonly operator: "gt" | "gte" | "lt" | "lte"; readonly value: string | number | Date; }
| { readonly type: "comparison"; readonly field: string | readonly string[]; readonly operator: "in"; readonly value: readonly unknown[]; }
A comparison of one entity field against a scalar value or value list.
| { readonly type: "and" | "or"; readonly filters: readonly FilterExpression[]; }
A portable filter tree evaluated by every repository backend.
Operators supported by a portable repository filter comparison.
Write-path operation options the data source passes to the driver.
Sort direction for a single field.
Options for IRepository.findPage — the parameter shape.
| "postgres"
| "mysql"
| "sqlserver"
| "cockroachdb"
| "mongodb"
| "sqlite"
The SQL connector a Prisma client is bound to.
The SQL dialects whose JSON extraction syntax this module can emit.
| "read-committed"
| "repeatable-read"
| "serializable"
Portable transaction isolation levels.
The data-access seam adapter-specific implementations provide, keeping
BaseRepository decoupled from concrete ORM clients.
Usage
import * as Database_plugin_with_repository_pattern__Unit_of_Work__and_ORM_adapters___Provides__DatabasePlugin__for_registering_database_access_through_the_framework_s_plugin_system__Supports_Prisma__Drizzle__and_in_memory_adapters__Every_export_is_documented_in_PUBLIC_API_md__AI_GUIDELINES__10__ from "database-plugin/src/index.ts";