@spfn/core 0.3.0-beta.33 → 0.3.0-beta.34

package/README.md

@@ -334,7 +334,7 @@ Each module has its own README with the API detail.
 | `@spfn/core/server` | Server entry: `defineServerConfig()` → `startServer()`, plus `createServerlessApp()` for Vercel. Middleware wiring, infra init, graceful shutdown. | [src/server](./src/server/README.md) |
 | `@spfn/core/nextjs` | Client-safe: `createApi<AppRouter>()`, `ApiError`, client types. Never touches `next/headers`. | [src/nextjs](./src/nextjs/README.md) |
 | `@spfn/core/nextjs/server` | Server-only: `createRpcProxy({ routeMap })`, `registerInterceptors`. Uses `next/headers`. | [src/nextjs](./src/nextjs/README.md) |
-| `@spfn/core/db` | PostgreSQL through Drizzle: CRUD helpers, `BaseRepository`, schema helpers, transactions, Postgres error mapping. One entry point for all of it. | [src/db](./src/db/README.md) |
+| `@spfn/core/db` | PostgreSQL through Drizzle: CRUD helpers, `BaseRepository`, `TenantRepository` for tables shared by many tenants, schema helpers, transactions, Postgres error mapping. One entry point for all of it. | [src/db](./src/db/README.md) |
 | `@spfn/core/db` → manager | Connection lifecycle, pool, primary/replica, health check, reconnect (`initDatabase`, `getDatabase`). Re-exported from `@spfn/core/db`. | [src/db/manager](./src/db/manager/README.md) |
 | `@spfn/core/db` → migrations | Which migrations each installed function package ships, and which the database has applied (`collectMigrationStatus`, `discoverFunctionMigrations`). What `spfn db status`, the boot gate and health all read. Re-exported from `@spfn/core/db`. | [src/db/migrations](https://github.com/fxylabs/spfn/blob/main/packages/core/src/db/migrations/index.ts) |
 | `@spfn/core/db` → schema | Drizzle column helpers (`id`, `uuid`, `timestamps`, `foreignKey`, `enumText`, `typedJsonb`, `softDelete`, …). Re-exported from `@spfn/core/db`. | [src/db/schema](./src/db/schema/README.md) |

package/dist/db/index.d.ts

@@ -1,7 +1,7 @@
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import postgres, { Sql } from 'postgres';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
-import { PgAsyncDatabase, PgAsyncTransaction, PgColumn, PgTable } from 'drizzle-orm/pg-core';
+import { PgAsyncDatabase, PgAsyncTransaction, PgColumn, PgTable, PgAsyncSelectBuilder, SelectedFields } from 'drizzle-orm/pg-core';
 import * as drizzle_orm from 'drizzle-orm';
 import { SQL, InferSelectModel, InferInsertModel, AnyRelations, EmptyRelations } from 'drizzle-orm';
 import * as hono_types from 'hono/types';
@@ -594,6 +594,31 @@ declare function generateDrizzleConfigFile(options?: DrizzleConfigOptions): stri
  * ```
  */
 declare function id(): drizzle_orm_pg_core.SetIsPrimaryKey<drizzle_orm_pg_core.PgBigSerial53Builder>;
+/**
+ * Tenant column for a table that many tenants share
+ *
+ * A not-null bigint holding the tenant's id. Declaring it is what makes the table
+ * tenant-aware: TenantRepository requires it, adds `tenant = $id` to every query
+ * it builds, and the development query warning checks hand-written queries for
+ * it. A table may declare one.
+ *
+ * It does not create an index — a drizzle column cannot. Declare the table's
+ * indexes in its third argument, each starting with the tenant column, so a
+ * query that filters on the tenant reads only that tenant's part of the index.
+ *
+ * @param name - Column name (default `tenant_id`)
+ * @returns not-null bigint column (JS `number`)
+ *
+ * @example
+ * ```typescript
+ * export const notes = schema.table('notes', {
+ *     id: id(),
+ *     tenantId: tenantKey(),
+ *     title: text('title').notNull(),
+ * }, (t) => [index('notes_tenant_id_idx').on(t.tenantId, t.id)]);
+ * ```
+ */
+declare function tenantKey(name?: string): drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgBigInt53Builder>;
 /**
  * Standard timestamp fields (createdAt, updatedAt)
  *
@@ -1836,79 +1861,31 @@ declare function deleteMany<T extends PgTable>(table: T, where: WhereObject<Infe
 declare function count<T extends PgTable>(table: T, where?: WhereObject<InferSelectModel<T>> | SQL | undefined): Promise<number>;
 
 /**
- * Base Repository Pattern
- *
- * Provides automatic database instance management with transaction context support.
- * Eliminates the need for manual `getDatabaseOrThrow()` calls in repository classes.
- *
- * Features:
- * - Automatic transaction context detection and usage
- * - Read/Write connection separation (with replica support)
- * - Type-safe schema generics
- * - Consistent database access pattern across all repositories
- * - Enhanced error tracking with repository context
- *
- * @example Basic Repository
- * ```typescript
- * import { BaseRepository } from '@spfn/core/db';
- * import { users } from './schema';
- * import { eq } from 'drizzle-orm';
- *
- * export class UserRepository extends BaseRepository {
- *     async findById(id: string) {
- *         // Uses read replica when available
- *         return await this.readDb
- *             .select()
- *             .from(users)
- *             .where(eq(users.id, id));
- *     }
+ * Query Utility Functions
  *
- *     async create(data: NewUser) {
- *         // Uses write primary
- *         return await this.db
- *             .insert(users)
- *             .values(data)
- *             .returning();
- *     }
- * }
- * ```
- *
- * @example With Transactions
- * ```typescript
- * import { runInTransaction } from '@spfn/core/db';
- *
- * const userRepo = new UserRepository();
- *
- * await runInTransaction(async () => {
- *     // Both db and readDb automatically use the transaction context
- *     const user = await userRepo.create({ name: 'John' });
- *     await userRepo.findById(user.id); // Uses same transaction
- * });
- * ```
+ * Common utilities for building database queries.
+ * Used by both helpers.ts and repository.ts to avoid code duplication.
  *
- * @example With Custom Schema Type
- * ```typescript
- * import type { AppRelations } from './relations';
- *
- * export class UserRepository extends BaseRepository<AppRelations> {
- *     // Now this.db and this.readDb preserve the app's Drizzle relations
- * }
- * ```
+ * @internal
+ */
+
+/** Options for a capped count. */
+interface CountOptions {
+    /**
+     * Stop counting past this many rows. The result is at most `cap + 1`, and
+     * `cap + 1` means "more than `cap`" — enough for a "1,000+" label without
+     * counting the whole table on every list request.
+     */
+    cap?: number;
+}
+
+/**
+ * Repository core
  *
- * @example With Enhanced Error Tracking
- * ```typescript
- * export class UserRepository extends BaseRepository {
- *     async updateStatus(id: string, status: string) {
- *         // Errors will include repository context automatically
- *         return await this.db
- *             .update(users)
- *             .set({ status })
- *             .where(eq(users.id, id))
- *             .returning();
- *     }
- * }
- * // On error: logs will show "UserRepository" context
- * ```
+ * The database access every repository shares: the write and read instances,
+ * which resolve to the ambient transaction when there is one, and the error
+ * context wrapper. BaseRepository and TenantRepository both extend it and add
+ * their own query methods.
  */
 
 /** Database surface available to repositories inside and outside transactions. */
@@ -1924,20 +1901,12 @@ declare class RepositoryError extends Error {
     constructor(message: string, repository: string, method?: string | undefined, table?: string | undefined, originalError?: Error | undefined);
 }
 /**
- * Base Repository class for database operations
- *
- * Provides automatic database instance management with transaction support.
- * Extend this class to create domain-specific repositories.
- *
- * The repository automatically detects if running within a transaction context
- * and uses the appropriate database instance:
- * - Inside transaction: Uses transaction DB
- * - Outside transaction: Uses global DB instance (with read/write separation)
+ * Shared base of BaseRepository and TenantRepository
  *
  * @template TRelations - Drizzle relations type (defaults to no relations)
  * @template TDatabase - PostgreSQL Drizzle driver type (defaults to postgres.js)
  */
-declare abstract class BaseRepository<TRelations extends AnyRelations = EmptyRelations, TDatabase extends DrizzleDatabase = PostgresJsDatabase<TRelations>> {
+declare abstract class RepositoryCore<TRelations extends AnyRelations = EmptyRelations, TDatabase extends DrizzleDatabase = PostgresJsDatabase<TRelations>> {
     /**
      * Write database instance
      *
@@ -2005,6 +1974,99 @@ declare abstract class BaseRepository<TRelations extends AnyRelations = EmptyRel
         method?: string;
         table?: string;
     }): Promise<T>;
+}
+
+/**
+ * Base Repository Pattern
+ *
+ * Provides automatic database instance management with transaction context support.
+ * Eliminates the need for manual `getDatabaseOrThrow()` calls in repository classes.
+ *
+ * Features:
+ * - Automatic transaction context detection and usage
+ * - Read/Write connection separation (with replica support)
+ * - Type-safe schema generics
+ * - Consistent database access pattern across all repositories
+ * - Enhanced error tracking with repository context
+ *
+ * @example Basic Repository
+ * ```typescript
+ * import { BaseRepository } from '@spfn/core/db';
+ * import { users } from './schema';
+ * import { eq } from 'drizzle-orm';
+ *
+ * export class UserRepository extends BaseRepository {
+ *     async findById(id: string) {
+ *         // Uses read replica when available
+ *         return await this.readDb
+ *             .select()
+ *             .from(users)
+ *             .where(eq(users.id, id));
+ *     }
+ *
+ *     async create(data: NewUser) {
+ *         // Uses write primary
+ *         return await this.db
+ *             .insert(users)
+ *             .values(data)
+ *             .returning();
+ *     }
+ * }
+ * ```
+ *
+ * @example With Transactions
+ * ```typescript
+ * import { runInTransaction } from '@spfn/core/db';
+ *
+ * const userRepo = new UserRepository();
+ *
+ * await runInTransaction(async () => {
+ *     // Both db and readDb automatically use the transaction context
+ *     const user = await userRepo.create({ name: 'John' });
+ *     await userRepo.findById(user.id); // Uses same transaction
+ * });
+ * ```
+ *
+ * @example With Custom Schema Type
+ * ```typescript
+ * import type { AppRelations } from './relations';
+ *
+ * export class UserRepository extends BaseRepository<AppRelations> {
+ *     // Now this.db and this.readDb preserve the app's Drizzle relations
+ * }
+ * ```
+ *
+ * @example With Enhanced Error Tracking
+ * ```typescript
+ * export class UserRepository extends BaseRepository {
+ *     async updateStatus(id: string, status: string) {
+ *         // Errors will include repository context automatically
+ *         return await this.db
+ *             .update(users)
+ *             .set({ status })
+ *             .where(eq(users.id, id))
+ *             .returning();
+ *     }
+ * }
+ * // On error: logs will show "UserRepository" context
+ * ```
+ */
+
+/**
+ * Base Repository class for database operations
+ *
+ * Provides automatic database instance management with transaction support.
+ * Extend this class to create domain-specific repositories.
+ *
+ * The repository automatically detects if running within a transaction context
+ * and uses the appropriate database instance:
+ * - Inside transaction: Uses transaction DB
+ * - Outside transaction: Uses global DB instance (with read/write separation)
+ *
+ * @template TRelations - Drizzle relations type (defaults to no relations)
+ * @template TDatabase - PostgreSQL Drizzle driver type (defaults to postgres.js)
+ */
+declare abstract class BaseRepository<TRelations extends AnyRelations = EmptyRelations, TDatabase extends DrizzleDatabase = PostgresJsDatabase<TRelations>> extends RepositoryCore<TRelations, TDatabase> {
     /**
      * Find a single record
      *
@@ -2190,15 +2252,123 @@ declare abstract class BaseRepository<TRelations extends AnyRelations = EmptyRel
      *
      * @param table - Drizzle table schema
      * @param where - Optional object or SQL condition
-     * @returns Number of records
+     * @param options - `cap` stops counting past that many rows
+     * @returns Number of records; with `cap`, at most `cap + 1`, which means "more than cap"
      *
      * @example
      * ```typescript
      * const total = await this._count(users);
      * const activeUsers = await this._count(users, { active: true });
+     *
+     * // A list label: 1001 reads as "1,000+"
+     * const shown = await this._count(users, undefined, { cap: 1000 });
      * ```
      */
-    protected _count<T extends PgTable>(table: T, where?: Record<string, any> | SQL | undefined): Promise<number>;
+    protected _count<T extends PgTable>(table: T, where?: Record<string, any> | SQL | undefined, options?: CountOptions): Promise<number>;
+}
+
+/**
+ * Tenant Repository
+ *
+ * A repository for tables that many tenants share. Every method takes the
+ * tenant id first and puts it into the query itself — the WHERE of a read,
+ * update or delete, the tenant column of an insert, the ON clause of each
+ * joined tenant-aware table — so no query this class builds can reach another
+ * tenant's rows.
+ *
+ * It does not extend BaseRepository: BaseRepository's `_findOne(table, where)`
+ * would stay callable without a tenant, and TypeScript does not let a subclass
+ * change a method's parameter list. Both extend RepositoryCore, so `this.db`,
+ * `this.readDb` and `withContext` behave the same. A query written by hand on
+ * `this.db` / `this.readDb` is not scoped, and neither is a subquery passed in
+ * as a condition or a join source; the development query warning reports one
+ * that leaves a tenant-aware table without its tenant condition.
+ *
+ * @example
+ * ```typescript
+ * export class NoteRepository extends TenantRepository
+ * {
+ *     async list(tenantId: number, after?: number)
+ *     {
+ *         return this._findManyKeyset(tenantId, notes, { cursorColumn: notes.id, after, limit: 50 });
+ *     }
+ *
+ *     async listWithAuthor(tenantId: number)
+ *     {
+ *         return this._select(tenantId, { title: notes.title, author: authors.name })
+ *             .from(notes)
+ *             .innerJoin(authors, eq(notes.authorId, authors.id));
+ *     }
+ * }
+ * ```
+ */
+
+type WhereInput = Record<string, any> | SQL | undefined;
+/**
+ * @template TRelations - Drizzle relations type (defaults to no relations)
+ * @template TDatabase - PostgreSQL Drizzle driver type (defaults to postgres.js)
+ */
+declare abstract class TenantRepository<TRelations extends AnyRelations = EmptyRelations, TDatabase extends DrizzleDatabase = PostgresJsDatabase<TRelations>> extends RepositoryCore<TRelations, TDatabase> {
+    /** One row of the tenant matching `where`, or null. */
+    protected _findOne<T extends PgTable>(tenantId: number, table: T, where: WhereInput): Promise<InferSelectModel<T> | null>;
+    /** Rows of the tenant, with the same options and DB_MAX_ROWS ceiling as BaseRepository. */
+    protected _findMany<T extends PgTable>(tenantId: number, table: T, options?: {
+        where?: WhereInput;
+        orderBy?: SQL | SQL[];
+        limit?: number;
+        offset?: number;
+    }): Promise<InferSelectModel<T>[]>;
+    /**
+     * Keyset (cursor) page of the tenant's rows. Index the table on
+     * (tenant column, cursor column) so a page reads only its own rows.
+     */
+    protected _findManyKeyset<T extends PgTable>(tenantId: number, table: T, options: {
+        cursorColumn: PgColumn;
+        limit: number;
+        after?: string | number | bigint | Date;
+        order?: 'asc' | 'desc';
+        where?: WhereInput;
+    }): Promise<InferSelectModel<T>[]>;
+    /** Number of the tenant's rows; with `cap`, at most `cap + 1` ("more than cap"). */
+    protected _count<T extends PgTable>(tenantId: number, table: T, where?: WhereInput, options?: CountOptions): Promise<number>;
+    /**
+     * A select whose `from` table and every joined tenant-aware table carry the
+     * tenant condition: the `from` table in WHERE, a joined one in its ON clause.
+     * `innerJoin` and `leftJoin` are scoped; right, full, cross and lateral joins,
+     * set operators and a joined view throw.
+     */
+    protected _select(tenantId: number): PgAsyncSelectBuilder<undefined>;
+    protected _select<TSelection extends SelectedFields>(tenantId: number, fields: TSelection): PgAsyncSelectBuilder<TSelection>;
+    /** Insert one row for the tenant; a different tenant value in `data` throws. */
+    protected _create<T extends PgTable>(tenantId: number, table: T, data: InferInsertModel<T>): Promise<InferSelectModel<T>>;
+    /** Insert rows for the tenant; every row is checked before any is written. */
+    protected _createMany<T extends PgTable>(tenantId: number, table: T, data: InferInsertModel<T>[]): Promise<InferSelectModel<T>[]>;
+    /**
+     * Insert, or update on conflict. The conflict target must include the
+     * tenant column: on `id` alone, an insert could collide with another
+     * tenant's row and update it.
+     */
+    protected _upsert<T extends PgTable>(tenantId: number, table: T, data: InferInsertModel<T>, options: {
+        target: PgColumn[];
+        set?: Partial<InferInsertModel<T>> | Record<string, SQL | any>;
+    }): Promise<InferSelectModel<T>>;
+    /** Update the tenant's rows matching `where`; returns the first, or null. */
+    protected _updateOne<T extends PgTable>(tenantId: number, table: T, where: WhereInput, data: Partial<InferInsertModel<T>>): Promise<InferSelectModel<T> | null>;
+    /** Update the tenant's rows matching `where`. */
+    protected _updateMany<T extends PgTable>(tenantId: number, table: T, where: WhereInput, data: Partial<InferInsertModel<T>>): Promise<InferSelectModel<T>[]>;
+    /** Delete the tenant's rows matching `where`; returns the first, or null. */
+    protected _deleteOne<T extends PgTable>(tenantId: number, table: T, where: WhereInput): Promise<InferSelectModel<T> | null>;
+    /** Delete the tenant's rows matching `where`. */
+    protected _deleteMany<T extends PgTable>(tenantId: number, table: T, where: WhereInput): Promise<InferSelectModel<T>[]>;
+    private updateRows;
+    private deleteRows;
+    /** `tenant condition AND where`, after checking the tenant id and the table. */
+    private tenantWhere;
+    /** As tenantWhere, and `where` itself must filter on something besides the tenant. */
+    private requiredWhere;
+    private withTenantValue;
+    private assertTenantUnchanged;
+    private assertTargetHasTenant;
 }
 
-export { type AfterCommitCallback, type AfterRollbackCallback, BaseRepository, type BeforeCommitCallback, type DatabaseClients, type DatabaseInitOptions, type DatabaseOptions, type DatabaseProvider, type DatabaseTransaction, type DefaultDatabase, type DrizzleConfigOptions, type DrizzleDatabase, type FunctionMigrationEntry, type FunctionMigrationInfo, type MigrationStatus, type MigrationStatusDb, type MigrationTargetStatus, type NestedFrameGate, PROJECT_MIGRATIONS_TABLE, PROJECT_TARGET_NAME, type PoolConfig, RUN_MIGRATIONS_HINT, type RenderableDrizzleConfig, type RepositoryDatabase, RepositoryError, type RetryConfig, type RunInTransactionOptions, type TransactionContext, type TransactionDB, Transactional, type TransactionalOptions, auditFields, checkConnection, closeDatabase, collectMigrationStatus, count, countPendingMigrations, create, createDatabaseConnection, createDatabaseFromEnv, createMany, createSchema, deleteMany, deleteOne, detectDialect, discoverFunctionMigrations, enumText, filterPendingEntries, findMany, findOne, forceReconnectDatabase, foreignKey, formatPendingMigrations, fromPostgresError, functionMigrationsTable, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, getTransactionContext, hasMigrationTargets, id, initDatabase, isConnectionLevelError, migrationTargets, onAfterCommit, onAfterRollback, onBeforeCommit, optionalForeignKey, packageNameToSchema, pendingMigrationTargets, pendingMigrationsSummary, projectMigrationsDir, publishingFields, readMigrationEntries, renderDrizzleConfig, reportDatabaseError, resetConnectionErrorCounter, runInTransaction, runWithTransaction, setDatabase, setDatabaseProvider, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };
+export { type AfterCommitCallback, type AfterRollbackCallback, BaseRepository, type BeforeCommitCallback, type CountOptions, type DatabaseClients, type DatabaseInitOptions, type DatabaseOptions, type DatabaseProvider, type DatabaseTransaction, type DefaultDatabase, type DrizzleConfigOptions, type DrizzleDatabase, type FunctionMigrationEntry, type FunctionMigrationInfo, type MigrationStatus, type MigrationStatusDb, type MigrationTargetStatus, type NestedFrameGate, PROJECT_MIGRATIONS_TABLE, PROJECT_TARGET_NAME, type PoolConfig, RUN_MIGRATIONS_HINT, type RenderableDrizzleConfig, type RepositoryDatabase, RepositoryError, type RetryConfig, type RunInTransactionOptions, TenantRepository, type TransactionContext, type TransactionDB, Transactional, type TransactionalOptions, auditFields, checkConnection, closeDatabase, collectMigrationStatus, count, countPendingMigrations, create, createDatabaseConnection, createDatabaseFromEnv, createMany, createSchema, deleteMany, deleteOne, detectDialect, discoverFunctionMigrations, enumText, filterPendingEntries, findMany, findOne, forceReconnectDatabase, foreignKey, formatPendingMigrations, fromPostgresError, functionMigrationsTable, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, getTransactionContext, hasMigrationTargets, id, initDatabase, isConnectionLevelError, migrationTargets, onAfterCommit, onAfterRollback, onBeforeCommit, optionalForeignKey, packageNameToSchema, pendingMigrationTargets, pendingMigrationsSummary, projectMigrationsDir, publishingFields, readMigrationEntries, renderDrizzleConfig, reportDatabaseError, resetConnectionErrorCounter, runInTransaction, runWithTransaction, setDatabase, setDatabaseProvider, softDelete, tenantKey, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };