@arki/db 0.1.0

package/dist/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,SAAS,4BAA+B,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,YAAY,4BAAkC,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,eAAe,4BAAqC,CAAC;AAElE;;;GAGG"}

package/dist/debug.js

@@ -0,0 +1,21 @@
+import { createDebugLogger } from '@arki/log/debug';
+/**
+ * Debug logger for database initialization and connection operations
+ * Enable with: DEBUG=db:init
+ */
+export const debugInit = createDebugLogger('db:init');
+/**
+ * Debug logger for database factory operations
+ * Enable with: DEBUG=db:factory
+ */
+export const debugFactory = createDebugLogger('db:factory');
+/**
+ * Debug logger for projection builder operations
+ * Enable with: DEBUG=db:projection
+ */
+export const debugProjection = createDebugLogger('db:projection');
+/**
+ * Enable all database debug logs
+ * Enable with: DEBUG=db:*
+ */
+//# sourceMappingURL=debug.js.map

package/dist/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;AAEtD;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;AAE5D;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC,eAAe,CAAC,CAAC;AAElE;;;GAGG"}

package/dist/dot.d.ts

@@ -0,0 +1,87 @@
+/**
+ * DOT adapter for `@arki/db`.
+ *
+ * Wraps the Drizzle database initialization as a `DotPip`. The pip
+ * opens a database connection in `boot`, publishes the Drizzle handle as
+ * `services.db`, and tears down the underlying client in `dispose`
+ * (reverse-topological order).
+ *
+ * Two drivers are supported:
+ *   - `'pg'` (default) — `node-postgres` pool. Reads `DB_URL` and the
+ *     `DB_POOL_*` env vars via `@arki/db`'s built-in env loader.
+ *   - `'pglite'` — embedded PGlite. Pass `dataDir`, or `memory: true` for
+ *     an in-memory instance. Use for tests, single-binary apps, or local
+ *     development without a real Postgres server.
+ *
+ * @example
+ * ```ts
+ * import { defineApp } from '@arki/dot';
+ * import { db } from '@arki/db/dot';
+ * import { defineRelations } from '@arki/db/orm';
+ * import { schema } from './schema';
+ *
+ * const relations = defineRelations(schema, (b) => ({ ... }));
+ *
+ * // Node-postgres (default), reads DB_URL from env:
+ * const app = await defineApp('my-app')
+ *   .use(db({ relations }))
+ *   .boot();
+ *
+ * // PGlite in-memory (great for tests):
+ * const testApp = await defineApp('test')
+ *   .use(db({ driver: 'pglite', memory: true, relations }))
+ *   .boot();
+ * ```
+ *
+ * The `@arki/dot` package is an OPTIONAL peer of `@arki/db`. Importing
+ * this adapter without `@arki/dot` installed will fail at module load —
+ * that is intentional: the adapter only makes sense in a DOT app.
+ */
+import type { AnyRelations, Logger } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type { PgliteDatabase } from 'drizzle-orm/pglite';
+import { type DotPip } from '@arki/dot/pip';
+import { type PgliteInitOptions } from './runtime-local.js';
+/**
+ * Common options shared by all DB driver variants.
+ */
+type BaseDbDotOptions<TRelations extends AnyRelations> = {
+    /** Drizzle 1.0 relations config (build via `defineRelations`). */
+    readonly relations: TRelations;
+    /** Drizzle logger override — `true`/`false` or a custom `Logger` instance. */
+    readonly logger?: boolean | Logger;
+    /**
+     * Pip name override. Defaults to `'db'`. Use this only when composing
+     * multiple database scopes inside the same app (e.g. primary + reporting).
+     */
+    readonly name?: string;
+};
+/** Options for the node-postgres driver (the default). */
+export type PgDbDotOptions<TRelations extends AnyRelations> = BaseDbDotOptions<TRelations> & {
+    /** Driver discriminant. Defaults to `'pg'` when omitted. */
+    readonly driver?: 'pg';
+};
+/** Options for the embedded-PGlite driver. */
+export type PgliteDbDotOptions<TRelations extends AnyRelations> = BaseDbDotOptions<TRelations> & PgliteInitOptions & {
+    /** Driver discriminant. */
+    readonly driver: 'pglite';
+};
+/** Discriminated union of all supported driver option shapes. */
+export type DbDotOptions<TRelations extends AnyRelations> = PgDbDotOptions<TRelations> | PgliteDbDotOptions<TRelations>;
+/**
+ * Services published by the db adapter. Keyed by the driver — for the
+ * default `'pg'` driver, `services.db` is a `NodePgDatabase<TRelations>`;
+ * for `'pglite'` it is a `PgliteDatabase<TRelations>`.
+ */
+export type DbServices<TRelations extends AnyRelations, TDriver extends 'pg' | 'pglite' = 'pg'> = {
+    readonly db: TDriver extends 'pglite' ? PgliteDatabase<TRelations> : NodePgDatabase<TRelations>;
+};
+/**
+ * Build a DOT pip that opens a Drizzle database and publishes it as
+ * a service. The kernel calls `dispose` in reverse-topological order to
+ * close the underlying pool / PGlite instance.
+ */
+export declare function db<TRelations extends AnyRelations>(options: PgDbDotOptions<TRelations>): DotPip<DbServices<TRelations, 'pg'>>;
+export declare function db<TRelations extends AnyRelations>(options: PgliteDbDotOptions<TRelations>): DotPip<DbServices<TRelations, 'pglite'>>;
+export {};
+//# sourceMappingURL=dot.d.ts.map

package/dist/dot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dot.d.ts","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;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;AACzD,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAG1D,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEhF;;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;IACnC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,cAAc,CAAC,UAAU,SAAS,YAAY,IACtD,gBAAgB,CAAC,UAAU,CAAC,GAC5B;IACA,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC;CACxB,CAAC;AAEJ,8CAA8C;AAC9C,MAAM,MAAM,kBAAkB,CAAC,UAAU,SAAS,YAAY,IAC1D,gBAAgB,CAAC,UAAU,CAAC,GAC5B,iBAAiB,GACjB;IACA,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;CAC3B,CAAC;AAEJ,iEAAiE;AACjE,MAAM,MAAM,YAAY,CAAC,UAAU,SAAS,YAAY,IACpD,cAAc,CAAC,UAAU,CAAC,GAC1B,kBAAkB,CAAC,UAAU,CAAC,CAAC;AAEnC;;;;GAIG;AACH,MAAM,MAAM,UAAU,CACpB,UAAU,SAAS,YAAY,EAC/B,OAAO,SAAS,IAAI,GAAG,QAAQ,GAAG,IAAI,IACpC;IACF,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,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;AACxC,wBAAgB,EAAE,CAAC,UAAU,SAAS,YAAY,EAChD,OAAO,EAAE,kBAAkB,CAAC,UAAU,CAAC,GACtC,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC"}

package/dist/dot.js

@@ -0,0 +1,104 @@
+/**
+ * DOT adapter for `@arki/db`.
+ *
+ * Wraps the Drizzle database initialization as a `DotPip`. The pip
+ * opens a database connection in `boot`, publishes the Drizzle handle as
+ * `services.db`, and tears down the underlying client in `dispose`
+ * (reverse-topological order).
+ *
+ * Two drivers are supported:
+ *   - `'pg'` (default) — `node-postgres` pool. Reads `DB_URL` and the
+ *     `DB_POOL_*` env vars via `@arki/db`'s built-in env loader.
+ *   - `'pglite'` — embedded PGlite. Pass `dataDir`, or `memory: true` for
+ *     an in-memory instance. Use for tests, single-binary apps, or local
+ *     development without a real Postgres server.
+ *
+ * @example
+ * ```ts
+ * import { defineApp } from '@arki/dot';
+ * import { db } from '@arki/db/dot';
+ * import { defineRelations } from '@arki/db/orm';
+ * import { schema } from './schema';
+ *
+ * const relations = defineRelations(schema, (b) => ({ ... }));
+ *
+ * // Node-postgres (default), reads DB_URL from env:
+ * const app = await defineApp('my-app')
+ *   .use(db({ relations }))
+ *   .boot();
+ *
+ * // PGlite in-memory (great for tests):
+ * const testApp = await defineApp('test')
+ *   .use(db({ driver: 'pglite', memory: true, relations }))
+ *   .boot();
+ * ```
+ *
+ * The `@arki/dot` package is an OPTIONAL peer of `@arki/db`. Importing
+ * this adapter without `@arki/dot` installed will fail at module load —
+ * that is intentional: the adapter only makes sense in a DOT app.
+ */
+import { defineDotPip } from '@arki/dot/pip';
+import { createDb } from './factory.js';
+import { initDbRuntimeLocal } from './runtime-local.js';
+export function db(options) {
+    const name = options.name ?? 'db';
+    const driver = options.driver ?? 'pg';
+    if (driver === 'pglite') {
+        const pgliteOptions = options;
+        // PGlite path: open the embedded instance and Drizzle handle in boot.
+        // We capture the raw PGlite client at boot-time so `dispose` can close
+        // it deterministically. `services.db` is the Drizzle handle only —
+        // exposing the PGlite client would leak driver-specific surface.
+        let pgliteHandle;
+        return defineDotPip({
+            name,
+            version: '0.1.0',
+            provides: ['db'],
+            configure(ctx) {
+                ctx.registerService('db', 'db');
+            },
+            async boot() {
+                const { db: handle, pglite } = await initDbRuntimeLocal({
+                    ...(pgliteOptions.dataDir !== undefined ? { dataDir: pgliteOptions.dataDir } : {}),
+                    ...(pgliteOptions.memory !== undefined ? { memory: pgliteOptions.memory } : {}),
+                    ...(pgliteOptions.extensions !== undefined ? { extensions: pgliteOptions.extensions } : {}),
+                }, { relations: pgliteOptions.relations });
+                pgliteHandle = pglite;
+                return { services: { db: handle } };
+            },
+            async dispose() {
+                if (pgliteHandle !== undefined) {
+                    await pgliteHandle.close();
+                    pgliteHandle = undefined;
+                }
+            },
+        });
+    }
+    // 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 defineDotPip({
+        name,
+        version: '0.1.0',
+        provides: ['db'],
+        configure(ctx) {
+            ctx.registerService('db', 'db');
+        },
+        boot() {
+            const handle = createDb({
+                relations: options.relations,
+                ...(options.logger !== undefined ? { logger: options.logger } : {}),
+            });
+            return { services: { db: handle } };
+        },
+        async dispose({ services }) {
+            // Drizzle exposes the underlying pg.Pool as `$client`. We call its
+            // `end()` to drain in-flight queries and close all sockets.
+            const pgHandle = services.db;
+            if (pgHandle.$client !== undefined) {
+                await pgHandle.$client.end();
+            }
+        },
+    });
+}
+//# sourceMappingURL=dot.js.map

package/dist/dot.js.map

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

package/dist/env.d.ts

@@ -0,0 +1,23 @@
+export declare const env: Readonly<{
+    PGUSER?: string | undefined;
+    PGPASSWORD?: string | undefined;
+    PGDATABASE?: string | undefined;
+    NODE_ENV: "development" | "production" | "test";
+    DB_URL: string;
+    PGHOST: string;
+    PGPORT: number;
+    PGSSLMODE: "disable" | "allow" | "prefer" | "require" | "verify-ca" | "verify-full";
+    DB_POOL_MIN: number;
+    DB_POOL_MAX: number;
+    DB_POOL_IDLE_TIMEOUT: number;
+    DB_POOL_CONNECTION_TIMEOUT: number;
+    DB_LOGGING: boolean;
+    DB_MIGRATIONS_FOLDER: string;
+    DB_SCHEMA: string;
+    DB_STATEMENT_TIMEOUT: number;
+    DB_QUERY_TIMEOUT: number;
+    DB_IDLE_IN_TRANSACTION_SESSION_TIMEOUT: number;
+    DB_SEED_ON_START: boolean;
+    DB_DROP_ON_START: boolean;
+}>;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;EAoFd,CAAC"}

package/dist/env.js

@@ -0,0 +1,77 @@
+import { createEnv } from '@t3-oss/env-core';
+import { z } from '@arki/contracts';
+export const env = createEnv({
+    onValidationError(issues) {
+        console.error('❌ [@arki/db] Invalid environment variables:\n' +
+            issues.map(i => `  ${(i.path ?? []).join('.')}: ${i.message}`).join('\n'));
+        throw new Error('Invalid environment variables');
+    },
+    /**
+     * Environment variables schema for database services (PostgreSQL)
+     */
+    server: {
+        // General Configuration
+        NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+        // Database Connection - Primary method (connection string)
+        // Either DB_URL must be provided (validated after env creation)
+        DB_URL: z.url(),
+        // Database Connection - Individual parameters (alternative to DB_URL)
+        PGUSER: z.string().optional(),
+        PGPASSWORD: z.string().optional(),
+        PGHOST: z.string().default('localhost'),
+        PGPORT: z.coerce.number().default(5432),
+        PGDATABASE: z.string().optional(),
+        PGSSLMODE: z.enum(['disable', 'allow', 'prefer', 'require', 'verify-ca', 'verify-full']).default('prefer'),
+        // Connection Pool Configuration
+        DB_POOL_MIN: z.coerce.number().default(2),
+        DB_POOL_MAX: z.coerce.number().default(20),
+        DB_POOL_IDLE_TIMEOUT: z.coerce.number().default(30_000), // 30 seconds
+        DB_POOL_CONNECTION_TIMEOUT: z.coerce.number().default(2000), // 2 seconds
+        // Database Behavior Configuration
+        DB_LOGGING: z.coerce.boolean().default(false),
+        DB_MIGRATIONS_FOLDER: z.string().default('./migrations'),
+        DB_SCHEMA: z.string().default('public'),
+        // Performance and Reliability
+        DB_STATEMENT_TIMEOUT: z.coerce.number().default(30_000), // 30 seconds
+        DB_QUERY_TIMEOUT: z.coerce.number().default(60_000), // 1 minute
+        DB_IDLE_IN_TRANSACTION_SESSION_TIMEOUT: z.coerce.number().default(10_000), // 10 seconds
+        // Development and Testing
+        DB_SEED_ON_START: z
+            .string()
+            .optional()
+            .transform(val => val === 'true'),
+        DB_DROP_ON_START: z
+            .string()
+            .optional()
+            .transform(val => val === 'true'),
+    },
+    client: {},
+    clientPrefix: '',
+    /**
+     * Destructure all variables from `process.env` to make sure they aren't tree-shaken away.
+     */
+    runtimeEnv: {
+        NODE_ENV: process.env['NODE_ENV'],
+        DB_URL: process.env['DB_URL'],
+        PGUSER: process.env['PGUSER'],
+        PGPASSWORD: process.env['PGPASSWORD'],
+        PGHOST: process.env['PGHOST'],
+        PGPORT: process.env['PGPORT'],
+        PGDATABASE: process.env['PGDATABASE'],
+        PGSSLMODE: process.env['PGSSLMODE'],
+        DB_POOL_MIN: process.env['DB_POOL_MIN'],
+        DB_POOL_MAX: process.env['DB_POOL_MAX'],
+        DB_POOL_IDLE_TIMEOUT: process.env['DB_POOL_IDLE_TIMEOUT'],
+        DB_POOL_CONNECTION_TIMEOUT: process.env['DB_POOL_CONNECTION_TIMEOUT'],
+        DB_LOGGING: process.env['DB_LOGGING'],
+        DB_MIGRATIONS_FOLDER: process.env['DB_MIGRATIONS_FOLDER'],
+        DB_SCHEMA: process.env['DB_SCHEMA'],
+        DB_STATEMENT_TIMEOUT: process.env['DB_STATEMENT_TIMEOUT'],
+        DB_QUERY_TIMEOUT: process.env['DB_QUERY_TIMEOUT'],
+        DB_IDLE_IN_TRANSACTION_SESSION_TIMEOUT: process.env['DB_IDLE_IN_TRANSACTION_SESSION_TIMEOUT'],
+        DB_SEED_ON_START: process.env['DB_SEED_ON_START'],
+        DB_DROP_ON_START: process.env['DB_DROP_ON_START'],
+    },
+    skipValidation: !!process.env['SKIP_ENV_VALIDATION'] || !!process.env['CI'] || process.env['NODE_ENV'] === 'test',
+});
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

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

package/dist/factory.d.ts

@@ -0,0 +1,18 @@
+import type { AnyRelations, Logger } from 'drizzle-orm';
+/**
+ * Create a database connection using environment configuration.
+ *
+ * `relations` is required (mark the field even when empty) so TypeScript can
+ * infer the precise relations type for `db.query.*` autocomplete. Use
+ * `defineRelations(schema, callback)` to build the value.
+ *
+ * @throws Error if DB_URL is not configured.
+ */
+export declare function createDb<TRelations extends AnyRelations>(config: {
+    relations: TRelations;
+    logger?: boolean | Logger | undefined;
+}): import("drizzle-orm/node-postgres").NodePgDatabase<TRelations> & {
+    $client: import("pg").Pool;
+};
+export { getDbConnectionOptions, getDbConnectionParams } from './connection-options.js';
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAOxD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,UAAU,SAAS,YAAY,EACtD,MAAM,EAAE;IACN,SAAS,EAAE,UAAU,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;CACvC;;EAwBF;AAED,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/factory.js

@@ -0,0 +1,31 @@
+import { getDbConnectionOptions } from './connection-options.js';
+import { debugFactory } from './debug.js';
+import { env } from './env.js';
+import { initDbWithOptions } from './init.js';
+/**
+ * Create a database connection using environment configuration.
+ *
+ * `relations` is required (mark the field even when empty) so TypeScript can
+ * infer the precise relations type for `db.query.*` autocomplete. Use
+ * `defineRelations(schema, callback)` to build the value.
+ *
+ * @throws Error if DB_URL is not configured.
+ */
+export function createDb(config) {
+    debugFactory('[factory] Creating database from environment configuration');
+    const connectionUrl = env.DB_URL;
+    if (!connectionUrl) {
+        debugFactory('[factory] Database creation failed: DB_URL not configured');
+        throw new Error('Database URL is not configured. Please set DB_URL environment variable.');
+    }
+    const connectionOptions = getDbConnectionOptions();
+    debugFactory('[factory] Connection options (min: %d, max: %d, idleTimeout: %dms, connTimeout: %dms)', connectionOptions.min, connectionOptions.max, connectionOptions.idleTimeoutMillis, connectionOptions.connectionTimeoutMillis);
+    const db = initDbWithOptions(connectionOptions, {
+        ...config,
+        logger: config.logger ?? (env.DB_LOGGING || env.NODE_ENV === 'development'),
+    });
+    debugFactory('[factory] Database created successfully');
+    return db;
+}
+export { getDbConnectionOptions, getDbConnectionParams } from './connection-options.js';
+//# sourceMappingURL=factory.js.map

package/dist/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CACtB,MAGC;IAED,YAAY,CAAC,4DAA4D,CAAC,CAAC;IAE3E,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,CAAC;IACjC,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,YAAY,CAAC,2DAA2D,CAAC,CAAC;QAC1E,MAAM,IAAI,KAAK,CAAC,yEAAyE,CAAC,CAAC;IAC7F,CAAC;IAED,MAAM,iBAAiB,GAAG,sBAAsB,EAAE,CAAC;IAEnD,YAAY,CAAC,uFAAuF,EAClG,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,CAAC,GAAG,EAC5C,iBAAiB,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,uBAAuB,CAAC,CAAC;IAElF,MAAM,EAAE,GAAG,iBAAiB,CAAa,iBAAiB,EAAE;QAC1D,GAAG,MAAM;QACT,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,QAAQ,KAAK,aAAa,CAAC;KAC5E,CAAC,CAAC;IAEH,YAAY,CAAC,yCAAyC,CAAC,CAAC;IAExD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/id-factory.d.ts

@@ -0,0 +1,85 @@
+import type { PgColumn } from 'drizzle-orm/pg-core';
+import { z } from '@arki/contracts';
+export declare const createId: () => string;
+export declare const createPrefixedId: <T extends string>(prefix: T) => `${T}${string}`;
+/**
+ * Type-safe ID factory that generates all ID-related utilities at once
+ *
+ * @param prefix - The prefix for the ID type (e.g., 'pt', 'usr', 'ant')
+ * @returns An object with create function, schema, and column helpers
+ *
+ * @example
+ * ```typescript
+ * export type PoetId = `pt${string}`;
+ * const poetId = createIdFactory<'pt', PoetId>('pt');
+ *
+ * export const createPoetId = poetId.create;
+ * export const poetIdSchema = poetId.schema;
+ *
+ * export const poets = schema.table('poets', {
+ *   id: poetId.primaryColumn(),
+ *   // ... other columns
+ * });
+ * ```
+ */
+export declare function createIdFactory<TPrefix extends string, TId extends `${TPrefix}${string}`>(prefix: TPrefix): {
+    /**
+     * Creates a new ID with the specified prefix
+     */
+    create: () => TId;
+    /**
+     * Creates a new ID with the specified prefix
+     */
+    make: () => TId;
+    /**
+     * Creates a new ID with the specified prefix
+     */
+    new: () => TId;
+    schema: z.ZodPipe<z.ZodString, z.ZodTransform<Awaited<TId>, string>> | z.ZodPipe<z.core.$ZodBranded<z.ZodString, TId, "out">, z.ZodTransform<Awaited<TId>, string & z.core.$brand<TId>>>;
+    /**
+     * Drizzle column helper for primary key columns
+     * Automatically configures as varchar(256), not null, primary key, with proper type and default
+     */
+    primaryColumn: (name?: string) => import("drizzle-orm/pg-core").SetHasRuntimeDefault<import("drizzle-orm/pg-core").Set$Type<import("drizzle-orm/pg-core").SetIsPrimaryKey<import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgVarcharBuilder<[string, ...string[]]>>>, TId>>;
+    optionalColumn: (name: string) => import("drizzle-orm/pg-core").SetHasRuntimeDefault<import("drizzle-orm/pg-core").Set$Type<import("drizzle-orm/pg-core").PgVarcharBuilder<[string, ...string[]]>, TId | null>>;
+    requiredColumn: (name: string) => import("drizzle-orm/pg-core").SetHasRuntimeDefault<import("drizzle-orm/pg-core").Set$Type<import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgVarcharBuilder<[string, ...string[]]>>, TId>>;
+    /**
+     * Drizzle column helper for foreign key reference columns
+     * Configures as varchar(256), not null, with proper type (no default or primary key)
+     */
+    reference: (name: string) => import("drizzle-orm/pg-core").Set$Type<import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgVarcharBuilder<[string, ...string[]]>>, TId>;
+    /**
+     * Drizzle column helper for optional foreign key reference columns
+     * Configures as varchar(256), nullable, with proper type
+     */
+    optionalReference: (name: string) => import("drizzle-orm/pg-core").Set$Type<import("drizzle-orm/pg-core").PgVarcharBuilder<[string, ...string[]]>, TId>;
+    /**
+     * Drizzle column helper for foreign key reference with relation
+     * Configures as varchar(256), not null, with proper type and foreign key constraint
+     */
+    foreignKey: (name: string, referenceFn: () => PgColumn, options?: {
+        onDelete?: "cascade" | "restrict" | "no action" | "set null" | "set default";
+    }) => import("drizzle-orm/pg-core").Set$Type<import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgVarcharBuilder<[string, ...string[]]>>, TId>;
+    /**
+     * Drizzle column helper for optional foreign key reference with relation
+     * Configures as varchar(256), nullable, with proper type and foreign key constraint
+     */
+    optionalForeignKey: (name: string, referenceFn: () => PgColumn, options?: {
+        onDelete?: "cascade" | "restrict" | "no action" | "set null" | "set default";
+    }) => import("drizzle-orm/pg-core").Set$Type<import("drizzle-orm/pg-core").PgVarcharBuilder<[string, ...string[]]>, TId>;
+    /**
+     * Creates a foreign key factory bound to a specific table
+     * This allows creating multiple foreign keys to the same table without repeating the reference
+     */
+    createForeignKeyFactory: (referenceFn: () => PgColumn) => {
+        required: (name: string, options?: {
+            onDelete?: "cascade" | "restrict" | "no action" | "set null" | "set default";
+        }) => import("drizzle-orm/pg-core").Set$Type<import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgVarcharBuilder<[string, ...string[]]>>, TId>;
+        optional: (name: string, options?: {
+            onDelete?: "cascade" | "restrict" | "no action" | "set null" | "set default";
+        }) => import("drizzle-orm/pg-core").Set$Type<import("drizzle-orm/pg-core").PgVarcharBuilder<[string, ...string[]]>, TId>;
+    };
+};
+export * from 'drizzle-orm';
+export { createInsertSchema, createSelectSchema, createSchemaFactory, createUpdateSchema } from 'drizzle-orm/zod';
+//# sourceMappingURL=id-factory.d.ts.map

package/dist/id-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-factory.d.ts","sourceRoot":"","sources":["../src/id-factory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EAAqB,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAGvD,eAAO,MAAM,QAAQ,cAAqB,CAAC;AAE3C,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,MAAM,EAAE,QAAQ,CAAC,KAAG,GAAG,CAAC,GAAG,MAAM,EAE3E,CAAC;AAkBF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,EAAE,EAAE,MAAM,EAAE,OAAO;IAatG;;OAEG;kBACS,GAAG;IACf;;OAEG;gBACO,GAAG;IACb;;OAEG;eACM,GAAG;;IAIZ;;;OAGG;;2BAWoB,MAAM;2BAQN,MAAM;IAS7B;;;OAGG;sBACe,MAAM;IAGxB;;;OAGG;8BACuB,MAAM;IAGhC;;;OAGG;uBAEK,MAAM,eACC,MAAM,QAAQ,YACjB;QAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,aAAa,CAAA;KAAE;IAO5F;;;OAGG;+BAEK,MAAM,eACC,MAAM,QAAQ,YACjB;QAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,aAAa,CAAA;KAAE;IAO5F;;;OAGG;2CACoC,MAAM,QAAQ;yBAE3C,MAAM,YACF;YAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,aAAa,CAAA;SAAE;yBAGpF,MAAM,YACF;YAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,aAAa,CAAA;SAAE;;EAMjG;AAGD,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/id-factory.js

@@ -0,0 +1,119 @@
+import { createId as createCuid } from '@paralleldrive/cuid2';
+import { varchar } from 'drizzle-orm/pg-core';
+import { COLUMN_ZOD_SCHEMA, z } from '@arki/contracts';
+// Core ID creation
+export const createId = () => createCuid();
+export const createPrefixedId = (prefix) => {
+    return `${prefix}${createId()}`;
+};
+/**
+ * Stash a Zod schema on a Drizzle column builder so that
+ * `@arki/contracts`'s `createSelectSchema`/`createInsertSchema`/`createUpdateSchema`
+ * wrappers auto-apply it as a refine — turning the brand from a phantom-only
+ * type into a real runtime check.
+ *
+ * The builder's `config` object is the SAME reference passed to the constructed
+ * column (see `PgVarcharBuilder.build` → `new PgVarchar(table, this.config)`),
+ * so writing here is readable from the column later.
+ */
+function tagColumnSchema(builder, schema) {
+    const cfg = builder.config;
+    cfg[COLUMN_ZOD_SCHEMA] = schema;
+    return builder;
+}
+/**
+ * Type-safe ID factory that generates all ID-related utilities at once
+ *
+ * @param prefix - The prefix for the ID type (e.g., 'pt', 'usr', 'ant')
+ * @returns An object with create function, schema, and column helpers
+ *
+ * @example
+ * ```typescript
+ * export type PoetId = `pt${string}`;
+ * const poetId = createIdFactory<'pt', PoetId>('pt');
+ *
+ * export const createPoetId = poetId.create;
+ * export const poetIdSchema = poetId.schema;
+ *
+ * export const poets = schema.table('poets', {
+ *   id: poetId.primaryColumn(),
+ *   // ... other columns
+ * });
+ * ```
+ */
+export function createIdFactory(prefix) {
+    /**
+     * Zod validation schema for the ID type. Uses refine instead of transform
+     * for better type safety; auto-applied at parse time by @arki/contracts'
+     * schema wrappers when this factory's columns appear on the table.
+     */
+    const schema = z
+        .string()
+        .startsWith(prefix)
+        .brand()
+        .transform(id => id);
+    const factory = {
+        /**
+         * Creates a new ID with the specified prefix
+         */
+        create: () => createPrefixedId(prefix),
+        /**
+         * Creates a new ID with the specified prefix
+         */
+        make: () => createPrefixedId(prefix),
+        /**
+         * Creates a new ID with the specified prefix
+         */
+        new: () => createPrefixedId(prefix),
+        schema,
+        /**
+         * Drizzle column helper for primary key columns
+         * Automatically configures as varchar(256), not null, primary key, with proper type and default
+         */
+        primaryColumn: (name = 'id') => tagColumnSchema(varchar(name, { length: 256 })
+            .notNull()
+            .primaryKey()
+            .$type()
+            .$defaultFn(() => createPrefixedId(prefix)), schema),
+        optionalColumn: (name) => tagColumnSchema(varchar(name, { length: 256 })
+            .$type()
+            .$defaultFn(() => null), schema),
+        requiredColumn: (name) => tagColumnSchema(varchar(name, { length: 256 })
+            .notNull()
+            .$type()
+            .$defaultFn(() => createPrefixedId(prefix)), schema),
+        /**
+         * Drizzle column helper for foreign key reference columns
+         * Configures as varchar(256), not null, with proper type (no default or primary key)
+         */
+        reference: (name) => tagColumnSchema(varchar(name, { length: 256 }).notNull().$type(), schema),
+        /**
+         * Drizzle column helper for optional foreign key reference columns
+         * Configures as varchar(256), nullable, with proper type
+         */
+        optionalReference: (name) => tagColumnSchema(varchar(name, { length: 256 }).$type(), schema),
+        /**
+         * Drizzle column helper for foreign key reference with relation
+         * Configures as varchar(256), not null, with proper type and foreign key constraint
+         */
+        foreignKey: (name, referenceFn, options) => tagColumnSchema(varchar(name, { length: 256 }).notNull().$type().references(referenceFn, options), schema),
+        /**
+         * Drizzle column helper for optional foreign key reference with relation
+         * Configures as varchar(256), nullable, with proper type and foreign key constraint
+         */
+        optionalForeignKey: (name, referenceFn, options) => tagColumnSchema(varchar(name, { length: 256 }).$type().references(referenceFn, options), schema),
+        /**
+         * Creates a foreign key factory bound to a specific table
+         * This allows creating multiple foreign keys to the same table without repeating the reference
+         */
+        createForeignKeyFactory: (referenceFn) => ({
+            required: (name, options) => factory.foreignKey(name, referenceFn, options),
+            optional: (name, options) => factory.optionalForeignKey(name, referenceFn, options),
+        }),
+    };
+    return factory;
+}
+// Re-export drizzle and zod utilities
+export * from 'drizzle-orm';
+export { createInsertSchema, createSelectSchema, createSchemaFactory, createUpdateSchema } from 'drizzle-orm/zod';
+//# sourceMappingURL=id-factory.js.map

package/dist/id-factory.js.map

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

package/dist/id.d.ts

@@ -0,0 +1,4 @@
+export declare const createId: () => string;
+export declare const createPrefixedId: <T extends string>(prefix: T) => `${T}${string}`;
+export * from './id-factory.js';
+//# sourceMappingURL=id.d.ts.map

package/dist/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../src/id.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,QAAQ,cAEpB,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,MAAM,EAAE,QAAQ,CAAC,KAAG,GAAG,CAAC,GAAG,MAAM,EAE3E,CAAC;AAGF,cAAc,iBAAiB,CAAC"}

package/dist/id.js

@@ -0,0 +1,10 @@
+import { createId as createCuid } from '@paralleldrive/cuid2';
+export const createId = () => {
+    return createCuid();
+};
+export const createPrefixedId = (prefix) => {
+    return `${prefix}${createId()}`;
+};
+// Re-export the new ID factory
+export * from './id-factory.js';
+//# sourceMappingURL=id.js.map