@arki/db 0.1.0 → 0.1.2

package/src/builder.ts

@@ -0,0 +1,359 @@
+import type { AnyRelations } from 'drizzle-orm';
+import { defineRelations } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type { PoolConfig } from 'pg';
+
+import { debugProjection } from './debug.js';
+import { initDbWithOptions } from './init.js';
+
+/**
+ * Projection middleware context
+ */
+export type ProjectionMiddlewareContext = {
+  next: () => Promise<void>;
+  meta: {
+    name: string;
+    eventCount: number;
+  };
+};
+
+/**
+ * Projection middleware function
+ */
+export type ProjectionMiddleware = (context: ProjectionMiddlewareContext) => Promise<void>;
+
+/**
+ * Projection handler context
+ */
+export type ProjectionHandlerContext<TRepos, TRelations extends AnyRelations = AnyRelations> = {
+  repo: TRepos;
+  db: NodePgDatabase<TRelations>;
+};
+
+/**
+ * Projection handler function
+ */
+export type ProjectionHandler<TEvent, TRepos, TRelations extends AnyRelations = AnyRelations> = (
+  events: TEvent[],
+  context: ProjectionHandlerContext<TRepos, TRelations>,
+) => Promise<void>;
+
+/**
+ * Projection builder interface
+ */
+export type ProjectionBuilder<
+  TEvent = never,
+  TRepos = never,
+  TRelations extends AnyRelations = AnyRelations,
+> = {
+  named<TName extends string>(name: TName): ProjectionBuilderWithName<TEvent, TRepos, TRelations, TName>;
+};
+
+export type ProjectionBuilderWithName<
+  _TEvent,
+  TRepos,
+  TRelations extends AnyRelations,
+  TName extends string,
+> = {
+  on<TEventType extends { type: string }>(
+    eventTypes: readonly TEventType['type'][] | TEventType['type'][],
+  ): ProjectionBuilderWithEvents<TEventType, TRepos, TRelations, TName>;
+};
+
+export type ProjectionBuilderWithEvents<
+  TEvent,
+  TRepos,
+  TRelations extends AnyRelations,
+  TName extends string,
+> = {
+  handle(handler: ProjectionHandler<TEvent, TRepos, TRelations>): ProjectionDefinition<TName>;
+};
+
+/**
+ * Emmett-compatible projection definition.
+ */
+export type ProjectionDefinition<TName extends string = string> = {
+  name: TName;
+  canHandle: string[];
+  handle: (events: { type: string }[]) => Promise<void>;
+};
+
+/**
+ * Database builder with projection support
+ */
+export type DbBuilder<TRelations extends AnyRelations, TRepos extends Record<string, unknown>> = {
+  readonly db: NodePgDatabase<TRelations>;
+  readonly isDev: boolean;
+
+  registerRepository<K extends string, R>(
+    key: K,
+    factory: (db: NodePgDatabase<TRelations>) => R,
+  ): DbBuilder<TRelations, TRepos & Record<K, R>>;
+
+  projectionMiddleware(fn: ProjectionMiddleware): ProjectionMiddleware;
+
+  readonly projection: ProjectionBuilderRoot<TRepos, TRelations>;
+};
+
+/**
+ * Projection builder root that can have middleware applied
+ */
+export type ProjectionBuilderRoot<TRepos, TRelations extends AnyRelations = AnyRelations> = {
+  use(middleware: ProjectionMiddleware): ProjectionBuilderRoot<TRepos, TRelations>;
+} & ProjectionBuilder<never, TRepos, TRelations>;
+
+/**
+ * Schema configuration step
+ */
+export type SchemaBuilder<TRelations extends AnyRelations> = {
+  create(options: {
+    connectionString: string;
+    isDev?: boolean;
+    poolConfig?: Partial<PoolConfig>;
+  }): DbBuilder<TRelations, Record<string, never>>;
+};
+
+/**
+ * Initial builder step
+ */
+export type InitialBuilder = {
+  /**
+   * Set the database tables. Internally builds a relations config via
+   * `defineRelations()` so consumers keep passing a plain table record.
+   *
+   * Use this for backends that don't define explicit relations and rely on
+   * auto-derivation (no joins). For explicit RQBv2 relations, prefer
+   * `.relations(...)` with a `defineRelations(tables, cb)` result.
+   */
+  schema<TSchema extends Record<string, unknown>>(
+    schema: TSchema,
+  ): SchemaBuilder<ReturnType<typeof defineRelations<TSchema>>>;
+
+  /**
+   * Pass a pre-built relations object (the result of
+   * `defineRelations(tables, cb)`) so the database knows about every table
+   * AND the explicit one/many relations declared by the application.
+   */
+  relations<TRelations extends AnyRelations>(relations: TRelations): SchemaBuilder<TRelations>;
+};
+
+/**
+ * Applies a middleware chain around a core handler function.
+ */
+function applyMiddleware(
+  middleware: ProjectionMiddleware[],
+  name: string,
+  eventCount: number,
+  coreHandler: () => Promise<void>,
+): Promise<void> {
+  const meta = { name, eventCount };
+
+  let next = coreHandler;
+  for (let i = middleware.length - 1; i >= 0; i--) {
+    const mw = middleware[i]!;
+    const currentNext = next;
+    next = () => mw({ next: currentNext, meta });
+  }
+
+  return next();
+}
+
+class ProjectionBuilderImpl<
+  TEvent,
+  TRepos,
+  TRelations extends AnyRelations,
+  TName extends string = string,
+>
+  implements
+    ProjectionBuilder<TEvent, TRepos, TRelations>,
+    ProjectionBuilderWithName<TEvent, TRepos, TRelations, TName>,
+    ProjectionBuilderWithEvents<TEvent, TRepos, TRelations, TName>,
+    ProjectionBuilderRoot<TRepos, TRelations>
+{
+  private _name?: string;
+  private _eventTypes?: string[];
+  private _middleware: ProjectionMiddleware[] = [];
+
+  constructor(
+    private readonly repos: TRepos,
+    private readonly _db: NodePgDatabase<TRelations>,
+    middleware?: ProjectionMiddleware[],
+  ) {
+    if (middleware) {
+      this._middleware = [...middleware];
+    }
+  }
+
+  named<N extends string>(name: N): ProjectionBuilderWithName<TEvent, TRepos, TRelations, N> {
+    debugProjection('[builder] Setting projection name: %s', name);
+    this._name = name;
+    return this as unknown as ProjectionBuilderImpl<TEvent, TRepos, TRelations, N>;
+  }
+
+  on<TEventType extends { type: string }>(
+    eventTypes: readonly TEventType['type'][] | TEventType['type'][],
+  ): ProjectionBuilderWithEvents<TEventType, TRepos, TRelations, TName> {
+    debugProjection('[builder] Registering event types: %o', eventTypes);
+    this._eventTypes = [...eventTypes];
+    return this as unknown as ProjectionBuilderImpl<TEventType, TRepos, TRelations, TName>;
+  }
+
+  handle(handler: ProjectionHandler<TEvent, TRepos, TRelations>): ProjectionDefinition<TName> {
+    if (!this._name) {
+      debugProjection('[builder] Error: Projection name is required');
+      throw new Error('Projection name is required. Call .named() first.');
+    }
+    if (!this._eventTypes) {
+      debugProjection('[builder] Error: Event types are required');
+      throw new Error('Event types are required. Call .on() first.');
+    }
+
+    const name = this._name as TName;
+    const eventTypes = this._eventTypes;
+    const middleware = this._middleware;
+    const repos = this.repos;
+    const db = this._db;
+
+    debugProjection('[builder] Creating projection definition (name: %s, eventTypes: %o, middlewareCount: %d)',
+      name, eventTypes, middleware.length);
+
+    return {
+      name,
+      canHandle: eventTypes,
+      handle: async (events: { type: string }[]) => {
+        const context: ProjectionHandlerContext<TRepos, TRelations> = { repo: repos, db };
+        const coreHandler = () => handler(events as TEvent[], context);
+
+        if (middleware.length > 0) {
+          await applyMiddleware(middleware, name, events.length, coreHandler);
+        } else {
+          await coreHandler();
+        }
+      },
+    };
+  }
+
+  use(middleware: ProjectionMiddleware): ProjectionBuilderRoot<TRepos, TRelations> {
+    debugProjection('[builder] Adding projection middleware (currentCount: %d)', this._middleware.length);
+    const newBuilder = new ProjectionBuilderImpl<TEvent, TRepos, TRelations, TName>(this.repos, this._db, [
+      ...this._middleware,
+      middleware,
+    ]);
+    debugProjection('[builder] Middleware added (newCount: %d)', this._middleware.length + 1);
+    return newBuilder;
+  }
+}
+
+class DbBuilderImpl<TRelations extends AnyRelations, TRepos extends Record<string, unknown>>
+  implements DbBuilder<TRelations, TRepos>
+{
+  readonly db: NodePgDatabase<TRelations>;
+  readonly isDev: boolean;
+  private _repos?: TRepos;
+  private readonly _repoFactories: Map<string, (db: NodePgDatabase<TRelations>) => unknown>;
+
+  constructor(
+    db: NodePgDatabase<TRelations>,
+    isDev: boolean,
+    repoFactories?: Map<string, (db: NodePgDatabase<TRelations>) => unknown>,
+  ) {
+    this.db = db;
+    this.isDev = isDev;
+    this._repoFactories = repoFactories ?? new Map();
+  }
+
+  registerRepository<K extends string, R>(
+    key: K,
+    factory: (db: NodePgDatabase<TRelations>) => R,
+  ): DbBuilder<TRelations, TRepos & Record<K, R>> {
+    debugProjection('[builder] Registering repository (key: %s, currentCount: %d)', key, this._repoFactories.size);
+    const newFactories = new Map(this._repoFactories);
+    newFactories.set(key, factory);
+    debugProjection('[builder] Repository registered (key: %s, newCount: %d)', key, newFactories.size);
+    return new DbBuilderImpl<TRelations, TRepos & Record<K, R>>(this.db, this.isDev, newFactories) as DbBuilder<
+      TRelations,
+      TRepos & Record<K, R>
+    >;
+  }
+
+  projectionMiddleware(fn: ProjectionMiddleware): ProjectionMiddleware {
+    return fn;
+  }
+
+  get projection(): ProjectionBuilderRoot<TRepos, TRelations> {
+    if (!this._repos) {
+      debugProjection('[builder] Initializing repositories from factories (count: %d)', this._repoFactories.size);
+      const repos: Record<string, unknown> = {};
+      for (const [key, factory] of this._repoFactories) {
+        debugProjection('[builder] Creating repository: %s', key);
+        repos[key] = factory(this.db);
+      }
+      this._repos = repos as TRepos;
+      debugProjection('[builder] All repositories initialized');
+    }
+    debugProjection('[builder] Creating projection builder');
+    return new ProjectionBuilderImpl<never, TRepos, TRelations>(this._repos, this.db);
+  }
+}
+
+class SchemaBuilderImpl<TRelations extends AnyRelations> implements SchemaBuilder<TRelations> {
+  constructor(private readonly relations: TRelations) {}
+
+  create(options: {
+    connectionString: string;
+    isDev?: boolean;
+    poolConfig?: Partial<PoolConfig>;
+  }): DbBuilder<TRelations, Record<string, never>> {
+    debugProjection('[builder] Creating database builder (isDev: %s, hasPoolConfig: %s)',
+      options.isDev ?? false, !!options.poolConfig);
+
+    const poolConfig: PoolConfig = {
+      connectionString: options.connectionString,
+      ...options.poolConfig,
+    };
+
+    debugProjection('[builder] Initializing database with pool config');
+    const db = initDbWithOptions<TRelations>(poolConfig, {
+      relations: this.relations,
+      logger: options.isDev,
+    });
+
+    debugProjection('[builder] Database builder created successfully');
+    return new DbBuilderImpl<TRelations, Record<string, never>>(db, options.isDev ?? false);
+  }
+}
+
+class InitialBuilderImpl implements InitialBuilder {
+  schema<TSchema extends Record<string, unknown>>(
+    schema: TSchema,
+  ): SchemaBuilder<ReturnType<typeof defineRelations<TSchema>>> {
+    debugProjection('[builder] Setting database schema (deriving relations via defineRelations)');
+    const relations = defineRelations(schema) as ReturnType<typeof defineRelations<TSchema>>;
+    return new SchemaBuilderImpl(relations);
+  }
+
+  relations<TRelations extends AnyRelations>(relations: TRelations): SchemaBuilder<TRelations> {
+    debugProjection('[builder] Setting database relations (explicit RQBv2)');
+    return new SchemaBuilderImpl(relations);
+  }
+}
+
+/**
+ * Initialize the database builder.
+ *
+ * @example
+ * ```typescript
+ * const d = initDb
+ *   .schema(schema)
+ *   .create({
+ *     connectionString: env.DB_URL,
+ *     isDev: process.env.NODE_ENV === 'development',
+ *   });
+ *
+ * const db = d.db;
+ * const projection = d.projection.named('my-proj').on(['EventA']).handle(async (events, ctx) => {
+ *   // handler
+ * });
+ * ```
+ */
+export const initDb: InitialBuilder = new InitialBuilderImpl();

package/src/bun.ts

@@ -0,0 +1,58 @@
+import { SQL } from 'bun';
+import type { AnyRelations } from 'drizzle-orm';
+import type { BunSQLDatabase } from 'drizzle-orm/bun-sql/postgres';
+import { drizzle } from 'drizzle-orm/bun-sql/postgres';
+import type { DrizzlePgConfig } from 'drizzle-orm/pg-core/utils';
+
+import { debugInit } from './debug.js';
+import { env } from './env.js';
+
+/**
+ * Initialize database with Bun's native SQL driver.
+ * @param connectionString - PostgreSQL connection string.
+ * @param config - Drizzle pg configuration.
+ */
+export const initDb = <TRelations extends AnyRelations>(
+  connectionString: string,
+  config: Omit<DrizzlePgConfig<TRelations>, 'relations'> & { relations: TRelations },
+): BunSQLDatabase<TRelations> => {
+  debugInit('[bun] Initializing database with connection string (logger: %s)', !!config.logger);
+
+  const client = new SQL(connectionString);
+
+  const db = drizzle<TRelations>({ ...config, client });
+
+  debugInit('[bun] Database initialized successfully with Bun SQL driver');
+
+  return db;
+};
+
+/**
+ * Create a database connection using environment configuration with Bun SQL.
+ * @param config - Drizzle pg configuration.
+ * @throws Error if DB_URL is not configured.
+ */
+export function createDb<TRelations extends AnyRelations>(
+  config: Omit<DrizzlePgConfig<TRelations>, 'relations'> & { relations: TRelations },
+): BunSQLDatabase<TRelations> {
+  debugInit('[bun] Creating database from environment configuration');
+
+  const connectionUrl = env.DB_URL;
+  if (!connectionUrl) {
+    debugInit('[bun] Database creation failed: DB_URL not configured');
+    throw new Error('Database URL is not configured. Please set DB_URL environment variable.');
+  }
+
+  const db = initDb(connectionUrl, {
+    ...config,
+    logger: config.logger ?? (env.DB_LOGGING || env.NODE_ENV === 'development'),
+  });
+
+  debugInit('[bun] Database created successfully');
+
+  return db;
+}
+
+export { getDbConnectionOptions, getDbConnectionParams } from './connection-options.js';
+
+export type { BunSQLDatabase } from 'drizzle-orm/bun-sql/postgres';

package/src/client/README.md

@@ -0,0 +1,5 @@
+# @arki/db/client
+
+Reserved client-side surface of `@arki/db`. V1 contains only type-level re-exports
+(zero runtime cost). Future Drizzle-on-client / Tier-3 sync work (Electric / PowerSync /
+Zero adapters) will land here. See [packages/offline/docs/2026-05-16-arki-offline-design.md](../../../offline/docs/2026-05-16-arki-offline-design.md).

package/src/client/ids.ts

@@ -0,0 +1,11 @@
+/**
+ * Branded ID type re-exports for the client surface.
+ *
+ * V1: @arki/contracts does not yet export named branded ID types.
+ * Future versions will re-export them here once they are defined, e.g.:
+ *
+ *   export type { UserId, OrgId, AssetId } from '@arki/contracts';
+ *
+ * See packages/offline/docs/2026-05-16-arki-offline-design.md §3.3.
+ */
+export type {};

package/src/client/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @arki/db/client — types-only client surface.
+ *
+ * V1 is intentionally empty: this subpath claims the namespace for future
+ * Drizzle-on-client / Tier-3 sync work (Electric / PowerSync / Zero adapters).
+ * No runtime imports are allowed here — this file must remain free of any
+ * server-only dependencies (postgres, drizzle-orm connection utilities, etc.).
+ *
+ * See packages/offline/docs/2026-05-16-arki-offline-design.md §3.3.
+ */
+export type * from './ids.js';

package/src/connection-options.ts

@@ -0,0 +1,49 @@
+import { debugFactory } from './debug.js';
+import { env } from './env.js';
+
+/**
+ * Get database connection options from environment variables
+ * @returns Connection options object for pg Pool
+ */
+export function getDbConnectionOptions() {
+  debugFactory('[factory] Retrieving database connection options from environment');
+
+  const connectionUrl = env.DB_URL;
+  const options = {
+    connectionString: connectionUrl,
+    min: env.DB_POOL_MIN,
+    max: env.DB_POOL_MAX,
+    idleTimeoutMillis: env.DB_POOL_IDLE_TIMEOUT,
+    connectionTimeoutMillis: env.DB_POOL_CONNECTION_TIMEOUT,
+    statement_timeout: env.DB_STATEMENT_TIMEOUT,
+    query_timeout: env.DB_QUERY_TIMEOUT,
+    idle_in_transaction_session_timeout: env.DB_IDLE_IN_TRANSACTION_SESSION_TIMEOUT,
+  };
+
+  debugFactory('[factory] Connection options retrieved (hasUrl: %s)', !!connectionUrl);
+
+  return options;
+}
+
+/**
+ * Get individual database connection parameters from environment variables
+ * Useful when DB_URL is not available but individual parameters are set
+ * @returns Connection parameters object
+ */
+export function getDbConnectionParams() {
+  debugFactory('[factory] Retrieving database connection parameters from environment');
+
+  const params = {
+    user: env.PGUSER,
+    password: env.PGPASSWORD,
+    host: env.PGHOST,
+    port: env.PGPORT,
+    database: env.PGDATABASE,
+    ssl: env.PGSSLMODE === 'disable' ? false : { rejectUnauthorized: env.PGSSLMODE === 'verify-full' },
+  };
+
+  debugFactory('[factory] Connection parameters retrieved (host: %s, port: %d, database: %s, ssl: %s)',
+    params.host, params.port, params.database, env.PGSSLMODE);
+
+  return params;
+}

package/src/debug.ts

@@ -0,0 +1,24 @@
+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:*
+ */