@arki/db 0.1.4 → 0.1.6

package/README.md

@@ -74,6 +74,69 @@ const idFactory = createIdFactory('post_');
 const postId = idFactory.next();
 ```
 
+## Feature-owned schema composition
+
+The schema has a different lifetime than runtime services: `drizzle-kit`
+imports tables statically, and `Db = typeof db` must exist before any DOT
+pip runs. Schema is therefore **module-composed, never runtime-contributed**.
+The layout:
+
+```text
+features/orders/tables.ts   — LEAF: pgTable/pgEnum definitions; imports nothing from core/
+core/schema.ts              — composeSchema(ordersTables, billingTables, …)
+core/relations.ts           — defineRelations(schema, …) — one app-level file, NOT sharded
+core/db.ts                  — type only: Db = ReturnType<typeof buildDb>['db']
+```
+
+```ts
+import { composeSchema } from '@arki/db';
+
+// Each feature exports a named record from its tables.ts leaf:
+export const ordersTables = { orders, orderItems, orderStatusEnum };
+
+// The app composes — a typed identity: runtime is Object.assign, the type
+// is the exact intersection. A duplicate table key is a COMPILE error
+// (the parameter type collapses to a named error object) AND a runtime
+// `DB_COMPOSITION_E001`, so drizzle sees a plain, collision-free object.
+export const schema = composeSchema(ordersTables, billingTables);
+```
+
+Point `drizzle-kit` at the leaves — no aggregation entrypoint needed, and
+enums are scanned per file (no aliased re-export tricks):
+
+```ts
+// drizzle.config.ts
+export default defineConfig({
+  schema: ['./src/features/**/tables.ts'],
+  // …
+});
+```
+
+The layering rule that keeps the module graph a DAG: `tables.ts` imports
+nothing from `core/`; `core/schema.ts` imports only leaves; feature code
+imports its own leaves plus the app's pip factory.
+
+### Cross-feature transactions: `createUnitOfWork`
+
+Feature services built at boot capture the singleton `db` — calling them
+inside a transaction would silently escape it. Cross-feature writes go
+through a typed unit of work instead:
+
+```ts
+import { createUnitOfWork } from '@arki/db';
+
+// Feature tx factories are STATIC exports: (tx: Database) => scoped repos.
+const uow = createUnitOfWork(db, {
+  orders: createOrdersTx,
+  billing: createBillingTx,
+});
+
+await uow(async tx => {
+  await tx.orders.create('ord_1');
+  await tx.billing.charge(500); // one transaction, both features, inferred types
+});
+```
+
 ## Subpath exports
 
 - `@arki/db` / `@arki/db/init` — `createDb`, `initDb`, `initDbWithOptions`. Under Bun, `./init` resolves to a Bun-native SQL driver.

package/dist/composition.d.ts

@@ -0,0 +1,33 @@
+export declare const DB_COMPOSITION_ERROR_CODES: {
+    readonly duplicateSchemaKey: "DB_COMPOSITION_E001";
+};
+export declare class DbCompositionError extends Error {
+    readonly code: (typeof DB_COMPOSITION_ERROR_CODES)[keyof typeof DB_COMPOSITION_ERROR_CODES];
+    constructor(args: {
+        readonly code: (typeof DB_COMPOSITION_ERROR_CODES)[keyof typeof DB_COMPOSITION_ERROR_CODES];
+        readonly message: string;
+    });
+}
+type SchemaSlice = Record<string, unknown>;
+type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (value: infer I) => void ? I : never;
+type DuplicateKeys<TSlices extends readonly SchemaSlice[], TSeen extends PropertyKey = never> = TSlices extends readonly [
+    infer Head,
+    ...infer Tail
+] ? Head extends SchemaSlice ? Tail extends readonly SchemaSlice[] ? (keyof Head & TSeen) | DuplicateKeys<Tail, TSeen | keyof Head> : keyof Head & TSeen : never : never;
+type DuplicateSchemaError<TKeys extends PropertyKey> = {
+    readonly 'ARKI_DB: duplicate schema keys': TKeys;
+};
+export type ComposedSchema<TSlices extends readonly SchemaSlice[]> = UnionToIntersection<TSlices[number]>;
+export declare function composeSchema<const TSlices extends readonly SchemaSlice[]>(...slices: DuplicateKeys<TSlices> extends never ? TSlices : readonly [DuplicateSchemaError<DuplicateKeys<TSlices>>]): ComposedSchema<TSlices>;
+export type TransactionalDb<TTransaction> = {
+    transaction<TResult>(fn: (tx: TTransaction) => Promise<TResult>): Promise<TResult>;
+};
+export type UnitOfWorkScopes<TFactories extends Record<string, (tx: never) => unknown>> = {
+    readonly [K in keyof TFactories]: ReturnType<TFactories[K]>;
+};
+export type UnitOfWork<TScopes> = <TResult>(fn: (scopes: TScopes) => Promise<TResult> | TResult) => Promise<TResult>;
+export declare function createUnitOfWork<TTransaction, const TFactories extends Record<string, (tx: TTransaction) => unknown>>(db: TransactionalDb<TTransaction>, factories: TFactories): UnitOfWork<{
+    readonly [K in keyof TFactories]: ReturnType<TFactories[K]>;
+}>;
+export {};
+//# sourceMappingURL=composition.d.ts.map

package/dist/composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../src/composition.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,0BAA0B;;CAE7B,CAAC;AAEX,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,OAAO,0BAA0B,CAAC,CAAC;gBAEhF,IAAI,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,OAAO,0BAA0B,CAAC,CAAC;QAC5F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B;CAKF;AAED,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE3C,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,OAAO,GAAG,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,GAC3G,CAAC,GACD,KAAK,CAAC;AAEV,KAAK,aAAa,CAAC,OAAO,SAAS,SAAS,WAAW,EAAE,EAAE,KAAK,SAAS,WAAW,GAAG,KAAK,IAAI,OAAO,SAAS,SAAS;IACvH,MAAM,IAAI;IACV,GAAG,MAAM,IAAI;CACd,GACG,IAAI,SAAS,WAAW,GACtB,IAAI,SAAS,SAAS,WAAW,EAAE,GACjC,CAAC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,aAAa,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,IAAI,CAAC,GAC9D,MAAM,IAAI,GAAG,KAAK,GACpB,KAAK,GACP,KAAK,CAAC;AAEV,KAAK,oBAAoB,CAAC,KAAK,SAAS,WAAW,IAAI;IACrD,QAAQ,CAAC,gCAAgC,EAAE,KAAK,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,cAAc,CAAC,OAAO,SAAS,SAAS,WAAW,EAAE,IAAI,mBAAmB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAE1G,wBAAgB,aAAa,CAAC,KAAK,CAAC,OAAO,SAAS,SAAS,WAAW,EAAE,EACxE,GAAG,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,SAAS,KAAK,GAAG,OAAO,GAAG,SAAS,CAAC,oBAAoB,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,GAClH,cAAc,CAAC,OAAO,CAAC,CAkBzB;AAED,MAAM,MAAM,eAAe,CAAC,YAAY,IAAI;IAC1C,WAAW,CAAC,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpF,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI;IACxF,QAAQ,EAAE,CAAC,IAAI,MAAM,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;CAC5D,CAAC;AAEF,MAAM,MAAM,UAAU,CAAC,OAAO,IAAI,CAAC,OAAO,EACxC,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,KAChD,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,wBAAgB,gBAAgB,CAC9B,YAAY,EACZ,KAAK,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,OAAO,CAAC,EAEtE,EAAE,EAAE,eAAe,CAAC,YAAY,CAAC,EACjC,SAAS,EAAE,UAAU,GACpB,UAAU,CAAC;IACZ,QAAQ,EAAE,CAAC,IAAI,MAAM,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;CAC5D,CAAC,CASD"}

package/dist/composition.js

@@ -0,0 +1,38 @@
+export const DB_COMPOSITION_ERROR_CODES = {
+    duplicateSchemaKey: 'DB_COMPOSITION_E001',
+};
+export class DbCompositionError extends Error {
+    code;
+    constructor(args) {
+        super(args.message);
+        this.name = 'DbCompositionError';
+        this.code = args.code;
+    }
+}
+export function composeSchema(...slices) {
+    const seen = new Set();
+    const schema = {};
+    for (const slice of slices) {
+        for (const key of Object.keys(slice)) {
+            if (seen.has(key)) {
+                throw new DbCompositionError({
+                    code: DB_COMPOSITION_ERROR_CODES.duplicateSchemaKey,
+                    message: `[db] schema key "${key}" is provided by more than one schema slice.`,
+                });
+            }
+            seen.add(key);
+            schema[key] = slice[key];
+        }
+    }
+    return schema;
+}
+export function createUnitOfWork(db, factories) {
+    return async (fn) => db.transaction(async (tx) => {
+        const scopes = {};
+        for (const [name, factory] of Object.entries(factories)) {
+            scopes[name] = factory(tx);
+        }
+        return fn(scopes);
+    });
+}
+//# sourceMappingURL=composition.js.map

package/dist/composition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.js","sourceRoot":"","sources":["../src/composition.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,kBAAkB,EAAE,qBAAqB;CACjC,CAAC;AAEX,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,CAA+E;IAE5F,YAAY,IAGX;QACC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;CACF;AAyBD,MAAM,UAAU,aAAa,CAC3B,GAAG,MAAgH;IAEnH,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,MAAM,GAAgB,EAAE,CAAC;IAE/B,KAAK,MAAM,KAAK,IAAI,MAAgC,EAAE,CAAC;QACrD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACrC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClB,MAAM,IAAI,kBAAkB,CAAC;oBAC3B,IAAI,EAAE,0BAA0B,CAAC,kBAAkB;oBACnD,OAAO,EAAE,oBAAoB,GAAG,8CAA8C;iBAC/E,CAAC,CAAC;YACL,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,OAAO,MAAiC,CAAC;AAC3C,CAAC;AAcD,MAAM,UAAU,gBAAgB,CAI9B,EAAiC,EACjC,SAAqB;IAIrB,OAAO,KAAK,EAAC,EAAE,EAAC,EAAE,CAChB,EAAE,CAAC,WAAW,CAAC,KAAK,EAAC,EAAE,EAAC,EAAE;QACxB,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YACxD,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,EAAE,CAAC,MAAyE,CAAC,CAAC;IACvF,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/dot.d.ts

@@ -1,7 +1,7 @@
 /**
  * DOT adapter for `@arki/db`.
  *
- * Wraps the Drizzle database initialization as a DOT pip. The pip
+ * Wraps the Drizzle database initialization as a DOT plugin. The plugin
  * opens a database connection in `boot`, publishes the Drizzle handle as
  * `services.db`, and tears down the underlying client in `dispose`
  * (reverse declaration order).
@@ -50,18 +50,18 @@
 import type { AnyRelations, Logger } from 'drizzle-orm';
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
 import type { PgliteDatabase } from 'drizzle-orm/pglite';
-import type { EmptyShape, Pip } from '@arki/dot/pip';
+import type { EmptyShape, Plugin } from '@arki/dot/plugin';
 import type { PgliteInitOptions } from './runtime-local.js';
 /**
- * Stable error codes thrown by the db pip. Exported so consumers and
+ * Stable error codes thrown by the db plugin. Exported so consumers and
  * coding agents can match against them — never parse the message.
  *
  * @see packages/dot/docs/principles.md — principle 1.3 ("errors are part
  * of the API") and principle 4 ("agent-discoverable everywhere").
  */
-export declare const DB_PIP_ERROR_CODES: {
+export declare const DB_PLUGIN_ERROR_CODES: {
     /** boot was called without a configured DB_URL (pg driver). */
-    readonly dbUrlNotConfigured: "DB_PIP_E001";
+    readonly dbUrlNotConfigured: "DB_PLUGIN_E001";
 };
 /**
  * Common options shared by all DB driver variants.
@@ -93,11 +93,11 @@ export type DbServices<TRelations extends AnyRelations, TDriver extends 'pg' | '
     readonly db: TDriver extends 'pglite' ? PgliteDatabase<TRelations> : NodePgDatabase<TRelations>;
 };
 /**
- * Build a DOT pip that opens a Drizzle database and publishes it as
+ * Build a DOT plugin that opens a Drizzle database and publishes it as
  * a service. The kernel calls `dispose` in reverse declaration order to
  * close the underlying pool / PGlite instance.
  */
-export declare function db<TRelations extends AnyRelations>(options: PgDbDotOptions<TRelations>): Pip<EmptyShape, DbServices<TRelations, 'pg'>>;
-export declare function db<TRelations extends AnyRelations>(options: PgliteDbDotOptions<TRelations>): Pip<EmptyShape, DbServices<TRelations, 'pglite'>>;
+export declare function db<TRelations extends AnyRelations>(options: PgDbDotOptions<TRelations>): Plugin<EmptyShape, DbServices<TRelations, 'pg'>>;
+export declare function db<TRelations extends AnyRelations>(options: PgliteDbDotOptions<TRelations>): Plugin<EmptyShape, DbServices<TRelations, 'pglite'>>;
 export {};
 //# sourceMappingURL=dot.d.ts.map

package/dist/dot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dot.d.ts","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAK5D;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;IAC7B,+DAA+D;;CAEvD,CAAC;AAEX;;GAEG;AACH,KAAK,gBAAgB,CAAC,UAAU,SAAS,YAAY,IAAI;IACvD,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACpC,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,cAAc,CAAC,UAAU,SAAS,YAAY,IAAI,gBAAgB,CAAC,UAAU,CAAC,GAAG;IAC3F,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC;CACxB,CAAC;AAEF,8CAA8C;AAC9C,MAAM,MAAM,kBAAkB,CAAC,UAAU,SAAS,YAAY,IAAI,gBAAgB,CAAC,UAAU,CAAC,GAC5F,iBAAiB,GAAG;IAClB,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;CAC3B,CAAC;AAEJ,iEAAiE;AACjE,MAAM,MAAM,YAAY,CAAC,UAAU,SAAS,YAAY,IAAI,cAAc,CAAC,UAAU,CAAC,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;AAExH;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,UAAU,SAAS,YAAY,EAAE,OAAO,SAAS,IAAI,GAAG,QAAQ,GAAG,IAAI,IAAI;IAChG,QAAQ,CAAC,EAAE,EAAE,OAAO,SAAS,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;CACjG,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,EAAE,CAAC,UAAU,SAAS,YAAY,EAChD,OAAO,EAAE,cAAc,CAAC,UAAU,CAAC,GAClC,GAAG,CAAC,UAAU,EAAE,UAAU,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;AACjD,wBAAgB,EAAE,CAAC,UAAU,SAAS,YAAY,EAChD,OAAO,EAAE,kBAAkB,CAAC,UAAU,CAAC,GACtC,GAAG,CAAC,UAAU,EAAE,UAAU,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC"}
+{"version":3,"file":"dot.d.ts","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAG3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAK5D;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;IAChC,+DAA+D;;CAEvD,CAAC;AAEX;;GAEG;AACH,KAAK,gBAAgB,CAAC,UAAU,SAAS,YAAY,IAAI;IACvD,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACpC,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,cAAc,CAAC,UAAU,SAAS,YAAY,IAAI,gBAAgB,CAAC,UAAU,CAAC,GAAG;IAC3F,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC;CACxB,CAAC;AAEF,8CAA8C;AAC9C,MAAM,MAAM,kBAAkB,CAAC,UAAU,SAAS,YAAY,IAAI,gBAAgB,CAAC,UAAU,CAAC,GAC5F,iBAAiB,GAAG;IAClB,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;CAC3B,CAAC;AAEJ,iEAAiE;AACjE,MAAM,MAAM,YAAY,CAAC,UAAU,SAAS,YAAY,IAAI,cAAc,CAAC,UAAU,CAAC,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;AAExH;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,UAAU,SAAS,YAAY,EAAE,OAAO,SAAS,IAAI,GAAG,QAAQ,GAAG,IAAI,IAAI;IAChG,QAAQ,CAAC,EAAE,EAAE,OAAO,SAAS,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;CACjG,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,EAAE,CAAC,UAAU,SAAS,YAAY,EAChD,OAAO,EAAE,cAAc,CAAC,UAAU,CAAC,GAClC,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;AACpD,wBAAgB,EAAE,CAAC,UAAU,SAAS,YAAY,EAChD,OAAO,EAAE,kBAAkB,CAAC,UAAU,CAAC,GACtC,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC"}

package/dist/dot.js

@@ -1,7 +1,7 @@
 /**
  * DOT adapter for `@arki/db`.
  *
- * Wraps the Drizzle database initialization as a DOT pip. The pip
+ * Wraps the Drizzle database initialization as a DOT plugin. The plugin
  * opens a database connection in `boot`, publishes the Drizzle handle as
  * `services.db`, and tears down the underlying client in `dispose`
  * (reverse declaration order).
@@ -47,20 +47,20 @@
  * this adapter without `@arki/dot` installed will fail at module load —
  * that is intentional: the adapter only makes sense in a DOT app.
  */
-import { pip, DotPipError } from '@arki/dot/pip';
+import { plugin, DotPluginError } from '@arki/dot/plugin';
 import { env } from './env.js';
 import { createDb } from './factory.js';
 import { initDbRuntimeLocal } from './runtime-local.js';
 /**
- * Stable error codes thrown by the db pip. Exported so consumers and
+ * Stable error codes thrown by the db plugin. Exported so consumers and
  * coding agents can match against them — never parse the message.
  *
  * @see packages/dot/docs/principles.md — principle 1.3 ("errors are part
  * of the API") and principle 4 ("agent-discoverable everywhere").
  */
-export const DB_PIP_ERROR_CODES = {
+export const DB_PLUGIN_ERROR_CODES = {
     /** boot was called without a configured DB_URL (pg driver). */
-    dbUrlNotConfigured: 'DB_PIP_E001',
+    dbUrlNotConfigured: 'DB_PLUGIN_E001',
 };
 export function db(options) {
     const driver = options.driver ?? 'pg';
@@ -71,7 +71,7 @@ export function db(options) {
         // it deterministically. `services.db` is the Drizzle handle only —
         // exposing the PGlite client would leak driver-specific surface.
         let pgliteHandle;
-        return pip({
+        return plugin({
             name: 'db',
             version: '0.1.0',
             configure(ctx) {
@@ -97,23 +97,23 @@ export function db(options) {
     // Node-postgres path: createDb already reads env vars and constructs the
     // pool. Drizzle owns the pool — closing it goes via the `$client.end()`
     // path that node-postgres exposes through Drizzle's handle.
-    return pip({
+    return plugin({
         name: 'db',
         version: '0.1.0',
         configure(ctx) {
             ctx.registerService('db', 'db');
         },
         boot() {
-            // Validate at the pip boundary so the DOT lifecycle gets a coded
+            // Validate at the plugin boundary so the DOT lifecycle gets a coded
             // error. `createDb` still throws raw `Error` for non-DOT consumers
             // (its public contract is unchanged); the check here makes sure we
             // never reach it without a URL.
             if (env.DB_URL === undefined || env.DB_URL === '') {
-                throw new DotPipError({
-                    code: DB_PIP_ERROR_CODES.dbUrlNotConfigured,
+                throw new DotPluginError({
+                    code: DB_PLUGIN_ERROR_CODES.dbUrlNotConfigured,
                     message: '[db] DB_URL is not configured.',
-                    remediation: 'Set DB_URL in the environment before booting the app, or switch the pip to the pglite driver for in-process databases.',
-                    docsUrl: 'https://arki.dev/dot/errors/db-pip-e001',
+                    remediation: 'Set DB_URL in the environment before booting the app, or switch the plugin to the pglite driver for in-process databases.',
+                    docsUrl: 'https://arki.dev/dot/errors/db-plugin-e001',
                 });
             }
             const handle = createDb({

package/dist/dot.js.map

@@ -1 +1 @@
-{"version":3,"file":"dot.js","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dot.js","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"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"}

package/dist/init.bun.d.ts

@@ -22,4 +22,6 @@ export declare const initDbWithOptions: <TRelations extends AnyRelations>(poolCo
 };
 export { createDb } from './factory.js';
 export { getDbConnectionOptions, getDbConnectionParams } from './connection-options.js';
+export { DB_COMPOSITION_ERROR_CODES, DbCompositionError, composeSchema, createUnitOfWork, } from './composition.js';
+export type { ComposedSchema, TransactionalDb, UnitOfWork, UnitOfWorkScopes, } from './composition.js';
 //# sourceMappingURL=init.bun.d.ts.map

package/dist/init.bun.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.bun.d.ts","sourceRoot":"","sources":["../src/init.bun.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAM1B,eAAO,MAAM,MAAM,GAAI,UAAU,SAAS,YAAY,EACpD,kBAAkB,MAAM,EACxB,QAAQ,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,EAAE,UAAU,CAAA;CAAE;;CAUnF,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,UAAU,SAAS,YAAY,EAC/D,YAAY;IACV,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,EACD,QAAQ,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,EAAE,UAAU,CAAA;CAAE;;CAoBnF,CAAC;AAEF,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"init.bun.d.ts","sourceRoot":"","sources":["../src/init.bun.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAM1B,eAAO,MAAM,MAAM,GAAI,UAAU,SAAS,YAAY,EACpD,kBAAkB,MAAM,EACxB,QAAQ,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,EAAE,UAAU,CAAA;CAAE;;CAUnF,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,UAAU,SAAS,YAAY,EAC/D,YAAY;IACV,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,EACD,QAAQ,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,EAAE,UAAU,CAAA;CAAE;;CAoBnF,CAAC;AAEF,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACxF,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,cAAc,EACd,eAAe,EACf,UAAU,EACV,gBAAgB,GACjB,MAAM,kBAAkB,CAAC"}

package/dist/init.bun.js

@@ -26,4 +26,5 @@ export const initDbWithOptions = (poolConfig, config) => {
 };
 export { createDb } from './factory.js';
 export { getDbConnectionOptions, getDbConnectionParams } from './connection-options.js';
+export { DB_COMPOSITION_ERROR_CODES, DbCompositionError, composeSchema, createUnitOfWork, } from './composition.js';
 //# sourceMappingURL=init.bun.js.map

package/dist/init.bun.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.bun.js","sourceRoot":"","sources":["../src/init.bun.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AACvD,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE1B,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,SAAS,CAAC,4DAA4D,CAAC,CAAC;AAExE,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,gBAAwB,EACxB,MAAkF,EAClF,EAAE;IACF,SAAS,CAAC,sEAAsE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAEnG,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACzC,MAAM,EAAE,GAAG,OAAO,CAAa,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAEtD,SAAS,CAAC,8CAA8C,CAAC,CAAC;IAE1D,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,UASC,EACD,MAAkF,EAClF,EAAE;IACF,SAAS,CAAC,kFAAkF,EAC1F,UAAU,CAAC,GAAG,IAAI,CAAC,EAAE,UAAU,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAE9D,MAAM,MAAM,GAAG,UAAU,CAAC,gBAAgB;QACxC,CAAC,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,gBAAgB,CAAC;QACtC,CAAC,CAAC,IAAI,GAAG,CAAC;YACN,QAAQ,EAAE,UAAU,CAAC,IAAI;YACzB,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,QAAQ,EAAE,UAAU,CAAC,QAAQ;YAC7B,QAAQ,EAAE,UAAU,CAAC,IAAI;YACzB,QAAQ,EAAE,UAAU,CAAC,QAAQ;SAC9B,CAAC,CAAC;IAEP,MAAM,EAAE,GAAG,OAAO,CAAa,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAEtD,SAAS,CAAC,gEAAgE,CAAC,CAAC;IAE5E,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC;AAEF,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"init.bun.js","sourceRoot":"","sources":["../src/init.bun.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AACvD,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE1B,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,SAAS,CAAC,4DAA4D,CAAC,CAAC;AAExE,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,gBAAwB,EACxB,MAAkF,EAClF,EAAE;IACF,SAAS,CAAC,sEAAsE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAEnG,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACzC,MAAM,EAAE,GAAG,OAAO,CAAa,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAEtD,SAAS,CAAC,8CAA8C,CAAC,CAAC;IAE1D,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,UASC,EACD,MAAkF,EAClF,EAAE;IACF,SAAS,CAAC,kFAAkF,EAC1F,UAAU,CAAC,GAAG,IAAI,CAAC,EAAE,UAAU,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAE9D,MAAM,MAAM,GAAG,UAAU,CAAC,gBAAgB;QACxC,CAAC,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,gBAAgB,CAAC;QACtC,CAAC,CAAC,IAAI,GAAG,CAAC;YACN,QAAQ,EAAE,UAAU,CAAC,IAAI;YACzB,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,QAAQ,EAAE,UAAU,CAAC,QAAQ;YAC7B,QAAQ,EAAE,UAAU,CAAC,IAAI;YACzB,QAAQ,EAAE,UAAU,CAAC,QAAQ;SAC9B,CAAC,CAAC;IAEP,MAAM,EAAE,GAAG,OAAO,CAAa,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAEtD,SAAS,CAAC,gEAAgE,CAAC,CAAC;IAE5E,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC;AAEF,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACxF,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC"}

package/dist/init.d.ts

@@ -13,4 +13,6 @@ export declare const initDbWithOptions: <TRelations extends AnyRelations>(poolCo
 };
 export { createDb } from './factory.js';
 export { getDbConnectionOptions, getDbConnectionParams } from './connection-options.js';
+export { DB_COMPOSITION_ERROR_CODES, DbCompositionError, composeSchema, createUnitOfWork, } from './composition.js';
+export type { ComposedSchema, TransactionalDb, UnitOfWork, UnitOfWorkScopes, } from './composition.js';
 //# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AASrC,eAAO,MAAM,MAAM,GAAI,UAAU,SAAS,YAAY,EACpD,kBAAkB,MAAM,EACxB,QAAQ,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,EAAE,UAAU,CAAA;CAAE;;CAYnF,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,UAAU,SAAS,YAAY,EAC/D,YAAY,UAAU,EACtB,QAAQ,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,EAAE,UAAU,CAAA;CAAE;;CAenF,CAAC;AAEF,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AASrC,eAAO,MAAM,MAAM,GAAI,UAAU,SAAS,YAAY,EACpD,kBAAkB,MAAM,EACxB,QAAQ,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,EAAE,UAAU,CAAA;CAAE;;CAYnF,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,UAAU,SAAS,YAAY,EAC/D,YAAY,UAAU,EACtB,QAAQ,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,GAAG;IAAE,SAAS,EAAE,UAAU,CAAA;CAAE;;CAenF,CAAC;AAEF,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACxF,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,cAAc,EACd,eAAe,EACf,UAAU,EACV,gBAAgB,GACjB,MAAM,kBAAkB,CAAC"}

package/dist/init.js

@@ -21,4 +21,5 @@ export const initDbWithOptions = (poolConfig, config) => {
 };
 export { createDb } from './factory.js';
 export { getDbConnectionOptions, getDbConnectionParams } from './connection-options.js';
+export { DB_COMPOSITION_ERROR_CODES, DbCompositionError, composeSchema, createUnitOfWork, } from './composition.js';
 //# sourceMappingURL=init.js.map

package/dist/init.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACpD,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC;AACrB,SAAS,CAAC,oDAAoD,CAAC,CAAC;AAEhE,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,gBAAwB,EACxB,MAAkF,EAClF,EAAE;IACF,SAAS,CAAC,kEAAkE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAE/F,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC;QACtB,gBAAgB;KACjB,CAAC,CAAC;IAEH,MAAM,EAAE,GAAG,OAAO,CAAa,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACtD,SAAS,CAAC,0CAA0C,CAAC,CAAC;IAEtD,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,UAAsB,EACtB,MAAkF,EAClF,EAAE;IACF,SAAS,CACP,8EAA8E,EAC9E,UAAU,CAAC,GAAG,IAAI,CAAC,EACnB,UAAU,CAAC,GAAG,IAAI,EAAE,EACpB,CAAC,CAAC,MAAM,CAAC,MAAM,CAChB,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC;IAEpC,MAAM,EAAE,GAAG,OAAO,CAAa,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACtD,SAAS,CAAC,4DAA4D,CAAC,CAAC;IAExE,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC;AAEF,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACpD,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC;AACrB,SAAS,CAAC,oDAAoD,CAAC,CAAC;AAEhE,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,gBAAwB,EACxB,MAAkF,EAClF,EAAE;IACF,SAAS,CAAC,kEAAkE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAE/F,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC;QACtB,gBAAgB;KACjB,CAAC,CAAC;IAEH,MAAM,EAAE,GAAG,OAAO,CAAa,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACtD,SAAS,CAAC,0CAA0C,CAAC,CAAC;IAEtD,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,UAAsB,EACtB,MAAkF,EAClF,EAAE;IACF,SAAS,CACP,8EAA8E,EAC9E,UAAU,CAAC,GAAG,IAAI,CAAC,EACnB,UAAU,CAAC,GAAG,IAAI,EAAE,EACpB,CAAC,CAAC,MAAM,CAAC,MAAM,CAChB,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC;IAEpC,MAAM,EAAE,GAAG,OAAO,CAAa,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACtD,SAAS,CAAC,4DAA4D,CAAC,CAAC;IAExE,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC;AAEF,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACxF,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arki/db",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Drizzle ORM repositories and database helpers for ARKI — Postgres + PGlite runtimes, projection builder, branded ID factory, and env-aware connection pooling.",
   "license": "MIT",
   "repository": {
@@ -110,8 +110,8 @@
   ],
   "dependencies": {
     "@arki/assert": "0.0.2",
-    "@arki/contracts": "0.0.2",
-    "@arki/env": "0.0.5",
+    "@arki/contracts": "0.0.3",
+    "@arki/env": "0.0.7",
     "@arki/log": "0.0.2",
     "@electric-sql/pglite": "^0.4.5",
     "@paralleldrive/cuid2": "^3.3.0",
@@ -122,7 +122,7 @@
     "zod": "4.3.5"
   },
   "peerDependencies": {
-    "@arki/dot": "^0.2.0"
+    "@arki/dot": "^0.4.0"
   },
   "peerDependenciesMeta": {
     "@arki/dot": {

package/src/composition.ts

@@ -0,0 +1,92 @@
+export const DB_COMPOSITION_ERROR_CODES = {
+  duplicateSchemaKey: 'DB_COMPOSITION_E001',
+} as const;
+
+export class DbCompositionError extends Error {
+  readonly code: (typeof DB_COMPOSITION_ERROR_CODES)[keyof typeof DB_COMPOSITION_ERROR_CODES];
+
+  constructor(args: {
+    readonly code: (typeof DB_COMPOSITION_ERROR_CODES)[keyof typeof DB_COMPOSITION_ERROR_CODES];
+    readonly message: string;
+  }) {
+    super(args.message);
+    this.name = 'DbCompositionError';
+    this.code = args.code;
+  }
+}
+
+type SchemaSlice = Record<string, unknown>;
+
+type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (value: infer I) => void
+  ? I
+  : never;
+
+type DuplicateKeys<TSlices extends readonly SchemaSlice[], TSeen extends PropertyKey = never> = TSlices extends readonly [
+  infer Head,
+  ...infer Tail,
+]
+  ? Head extends SchemaSlice
+    ? Tail extends readonly SchemaSlice[]
+      ? (keyof Head & TSeen) | DuplicateKeys<Tail, TSeen | keyof Head>
+      : keyof Head & TSeen
+    : never
+  : never;
+
+type DuplicateSchemaError<TKeys extends PropertyKey> = {
+  readonly 'ARKI_DB: duplicate schema keys': TKeys;
+};
+
+export type ComposedSchema<TSlices extends readonly SchemaSlice[]> = UnionToIntersection<TSlices[number]>;
+
+export function composeSchema<const TSlices extends readonly SchemaSlice[]>(
+  ...slices: DuplicateKeys<TSlices> extends never ? TSlices : readonly [DuplicateSchemaError<DuplicateKeys<TSlices>>]
+): ComposedSchema<TSlices> {
+  const seen = new Set<string>();
+  const schema: SchemaSlice = {};
+
+  for (const slice of slices as readonly SchemaSlice[]) {
+    for (const key of Object.keys(slice)) {
+      if (seen.has(key)) {
+        throw new DbCompositionError({
+          code: DB_COMPOSITION_ERROR_CODES.duplicateSchemaKey,
+          message: `[db] schema key "${key}" is provided by more than one schema slice.`,
+        });
+      }
+      seen.add(key);
+      schema[key] = slice[key];
+    }
+  }
+
+  return schema as ComposedSchema<TSlices>;
+}
+
+export type TransactionalDb<TTransaction> = {
+  transaction<TResult>(fn: (tx: TTransaction) => Promise<TResult>): Promise<TResult>;
+};
+
+export type UnitOfWorkScopes<TFactories extends Record<string, (tx: never) => unknown>> = {
+  readonly [K in keyof TFactories]: ReturnType<TFactories[K]>;
+};
+
+export type UnitOfWork<TScopes> = <TResult>(
+  fn: (scopes: TScopes) => Promise<TResult> | TResult,
+) => Promise<TResult>;
+
+export function createUnitOfWork<
+  TTransaction,
+  const TFactories extends Record<string, (tx: TTransaction) => unknown>,
+>(
+  db: TransactionalDb<TTransaction>,
+  factories: TFactories,
+): UnitOfWork<{
+  readonly [K in keyof TFactories]: ReturnType<TFactories[K]>;
+}> {
+  return async fn =>
+    db.transaction(async tx => {
+      const scopes: Record<string, unknown> = {};
+      for (const [name, factory] of Object.entries(factories)) {
+        scopes[name] = factory(tx);
+      }
+      return fn(scopes as { readonly [K in keyof TFactories]: ReturnType<TFactories[K]> });
+    });
+}

package/src/dot.ts

@@ -1,7 +1,7 @@
 /**
  * DOT adapter for `@arki/db`.
  *
- * Wraps the Drizzle database initialization as a DOT pip. The pip
+ * Wraps the Drizzle database initialization as a DOT plugin. The plugin
  * opens a database connection in `boot`, publishes the Drizzle handle as
  * `services.db`, and tears down the underlying client in `dispose`
  * (reverse declaration order).
@@ -52,8 +52,8 @@ import type { AnyRelations, Logger } from 'drizzle-orm';
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
 import type { PgliteDatabase } from 'drizzle-orm/pglite';
 
-import type { EmptyShape, Pip } from '@arki/dot/pip';
-import { pip, DotPipError } from '@arki/dot/pip';
+import type { EmptyShape, Plugin } from '@arki/dot/plugin';
+import { plugin, DotPluginError } from '@arki/dot/plugin';
 
 import type { PgliteInitOptions } from './runtime-local.js';
 import { env } from './env.js';
@@ -61,15 +61,15 @@ import { createDb } from './factory.js';
 import { initDbRuntimeLocal } from './runtime-local.js';
 
 /**
- * Stable error codes thrown by the db pip. Exported so consumers and
+ * Stable error codes thrown by the db plugin. Exported so consumers and
  * coding agents can match against them — never parse the message.
  *
  * @see packages/dot/docs/principles.md — principle 1.3 ("errors are part
  * of the API") and principle 4 ("agent-discoverable everywhere").
  */
-export const DB_PIP_ERROR_CODES = {
+export const DB_PLUGIN_ERROR_CODES = {
   /** boot was called without a configured DB_URL (pg driver). */
-  dbUrlNotConfigured: 'DB_PIP_E001',
+  dbUrlNotConfigured: 'DB_PLUGIN_E001',
 } as const;
 
 /**
@@ -108,19 +108,19 @@ export type DbServices<TRelations extends AnyRelations, TDriver extends 'pg' | '
 };
 
 /**
- * Build a DOT pip that opens a Drizzle database and publishes it as
+ * Build a DOT plugin that opens a Drizzle database and publishes it as
  * a service. The kernel calls `dispose` in reverse declaration order to
  * close the underlying pool / PGlite instance.
  */
 export function db<TRelations extends AnyRelations>(
   options: PgDbDotOptions<TRelations>,
-): Pip<EmptyShape, DbServices<TRelations, 'pg'>>;
+): Plugin<EmptyShape, DbServices<TRelations, 'pg'>>;
 export function db<TRelations extends AnyRelations>(
   options: PgliteDbDotOptions<TRelations>,
-): Pip<EmptyShape, DbServices<TRelations, 'pglite'>>;
+): Plugin<EmptyShape, DbServices<TRelations, 'pglite'>>;
 export function db<TRelations extends AnyRelations>(
   options: DbDotOptions<TRelations>,
-): Pip<EmptyShape, DbServices<TRelations, 'pg' | 'pglite'>> {
+): Plugin<EmptyShape, DbServices<TRelations, 'pg' | 'pglite'>> {
   const driver = options.driver ?? 'pg';
 
   if (driver === 'pglite') {
@@ -130,7 +130,7 @@ export function db<TRelations extends AnyRelations>(
     // it deterministically. `services.db` is the Drizzle handle only —
     // exposing the PGlite client would leak driver-specific surface.
     let pgliteHandle: { close: () => Promise<void> } | undefined;
-    return pip({
+    return plugin({
       name: 'db',
       version: '0.1.0',
       configure(ctx) {
@@ -154,30 +154,30 @@ export function db<TRelations extends AnyRelations>(
           pgliteHandle = undefined;
         }
       },
-    }) as Pip<EmptyShape, DbServices<TRelations, 'pg' | 'pglite'>>;
+    }) as Plugin<EmptyShape, DbServices<TRelations, 'pg' | 'pglite'>>;
   }
 
   // Node-postgres path: createDb already reads env vars and constructs the
   // pool. Drizzle owns the pool — closing it goes via the `$client.end()`
   // path that node-postgres exposes through Drizzle's handle.
-  return pip({
+  return plugin({
     name: 'db',
     version: '0.1.0',
     configure(ctx) {
       ctx.registerService('db', 'db');
     },
     boot(): DbServices<TRelations, 'pg'> {
-      // Validate at the pip boundary so the DOT lifecycle gets a coded
+      // Validate at the plugin boundary so the DOT lifecycle gets a coded
       // error. `createDb` still throws raw `Error` for non-DOT consumers
       // (its public contract is unchanged); the check here makes sure we
       // never reach it without a URL.
       if (env.DB_URL === undefined || env.DB_URL === '') {
-        throw new DotPipError({
-          code: DB_PIP_ERROR_CODES.dbUrlNotConfigured,
+        throw new DotPluginError({
+          code: DB_PLUGIN_ERROR_CODES.dbUrlNotConfigured,
           message: '[db] DB_URL is not configured.',
           remediation:
-            'Set DB_URL in the environment before booting the app, or switch the pip to the pglite driver for in-process databases.',
-          docsUrl: 'https://arki.dev/dot/errors/db-pip-e001',
+            'Set DB_URL in the environment before booting the app, or switch the plugin to the pglite driver for in-process databases.',
+          docsUrl: 'https://arki.dev/dot/errors/db-plugin-e001',
         });
       }
       const handle = createDb<TRelations>({
@@ -196,5 +196,5 @@ export function db<TRelations extends AnyRelations>(
         await pgHandle.$client.end();
       }
     },
-  }) as Pip<EmptyShape, DbServices<TRelations, 'pg' | 'pglite'>>;
+  }) as Plugin<EmptyShape, DbServices<TRelations, 'pg' | 'pglite'>>;
 }

package/src/init.bun.ts

@@ -56,3 +56,15 @@ export const initDbWithOptions = <TRelations extends AnyRelations>(
 
 export { createDb } from './factory.js';
 export { getDbConnectionOptions, getDbConnectionParams } from './connection-options.js';
+export {
+  DB_COMPOSITION_ERROR_CODES,
+  DbCompositionError,
+  composeSchema,
+  createUnitOfWork,
+} from './composition.js';
+export type {
+  ComposedSchema,
+  TransactionalDb,
+  UnitOfWork,
+  UnitOfWorkScopes,
+} from './composition.js';

package/src/init.ts

@@ -46,3 +46,15 @@ export const initDbWithOptions = <TRelations extends AnyRelations>(
 
 export { createDb } from './factory.js';
 export { getDbConnectionOptions, getDbConnectionParams } from './connection-options.js';
+export {
+  DB_COMPOSITION_ERROR_CODES,
+  DbCompositionError,
+  composeSchema,
+  createUnitOfWork,
+} from './composition.js';
+export type {
+  ComposedSchema,
+  TransactionalDb,
+  UnitOfWork,
+  UnitOfWorkScopes,
+} from './composition.js';