@zudojs/database 1.4.0 → 1.5.0

package/dist/migration/migration.runner.js

@@ -31,6 +31,10 @@ export class MigrationRunner {
         this.perItemTransaction = options.perItemTransaction ?? true;
         validateIdentifier(this.tableName, "migration table name");
         validateLockKey(this.lockKey, "migration lock key");
+        const detached = this.migrations.find((m) => m.transaction === false);
+        if (detached && !this.perItemTransaction) {
+            throw this.migrationError(`Migration "${detached.name}" sets transaction: false, which requires perItemTransaction: true.`, { metadata: { version: detached.version, name: detached.name } });
+        }
     }
     /**
      * Returns the migration status without executing anything.
@@ -69,16 +73,18 @@ export class MigrationRunner {
             return { applied: newlyApplied, skipped };
         }
         for (const migration of pending) {
-            const outcome = await this.client.transaction(async (transaction) => {
-                await this.acquireMigrationLock(transaction);
-                const applied = await this.getAppliedMigrations(transaction);
-                const existing = applied.find((r) => r.version === migration.version);
-                if (existing)
-                    return { record: existing, skipped: true };
-                await this.executeMigration(transaction, migration);
-                const record = await this.recordMigration(transaction, migration);
-                return { record, skipped: false };
-            }, this.buildTransactionOptions());
+            const outcome = migration.transaction === false
+                ? await this.applyDetached(migration)
+                : await this.client.transaction(async (transaction) => {
+                    await this.acquireMigrationLock(transaction);
+                    const applied = await this.getAppliedMigrations(transaction);
+                    const existing = applied.find((r) => r.version === migration.version);
+                    if (existing)
+                        return { record: existing, skipped: true };
+                    await this.executeMigration(transaction, migration);
+                    const record = await this.recordMigration(transaction, migration);
+                    return { record, skipped: false };
+                }, this.buildTransactionOptions());
             if (outcome.skipped)
                 skipped.push(outcome.record);
             else
@@ -86,6 +92,32 @@ export class MigrationRunner {
         }
         return { applied: newlyApplied, skipped };
     }
+    /**
+     * Applies a `transaction: false` migration: the applied check and the
+     * history record run in short transactions under the advisory lock, the
+     * body runs on the root client outside any transaction.
+     */
+    async applyDetached(migration) {
+        const existing = await this.client.transaction(async (transaction) => {
+            await this.acquireMigrationLock(transaction);
+            const applied = await this.getAppliedMigrations(transaction);
+            return applied.find((r) => r.version === migration.version);
+        }, this.buildTransactionOptions());
+        if (existing)
+            return { record: existing, skipped: true };
+        await this.executeMigration(this.rootClient(), migration);
+        const record = await this.client.transaction(async (transaction) => {
+            await this.acquireMigrationLock(transaction);
+            const applied = await this.getAppliedMigrations(transaction);
+            return (applied.find((r) => r.version === migration.version) ??
+                (await this.recordMigration(transaction, migration)));
+        }, this.buildTransactionOptions());
+        return { record, skipped: false };
+    }
+    /** The root Prisma client, handed to migrations that opt out of a transaction. */
+    rootClient() {
+        return this.client.getPrisma();
+    }
     /**
      * Alias of {@link migrate}.
      */
@@ -175,22 +207,41 @@ export class MigrationRunner {
             return rolledBack;
         }
         while (rolledBack.length < limit) {
-            const record = await this.client.transaction(async (transaction) => {
+            const step = await this.client.transaction(async (transaction) => {
                 await this.acquireMigrationLock(transaction);
                 const applied = await this.getAppliedMigrations(transaction);
                 const latest = applied[applied.length - 1];
                 if (!latest)
                     return null;
-                await this.revertRecord(transaction, latest);
-                return latest;
+                const migration = this.requireRollback(latest);
+                if (migration.transaction === false) {
+                    return { record: latest, detached: true };
+                }
+                await this.runDown(transaction, migration);
+                await this.deleteMigrationRecord(transaction, latest.version);
+                return { record: latest, detached: false };
             }, this.buildTransactionOptions());
-            if (!record)
+            if (!step)
                 break;
-            rolledBack.push(record);
+            if (step.detached)
+                await this.revertDetached(step.record);
+            rolledBack.push(step.record);
         }
         return rolledBack;
     }
+    /** Reverts a `transaction: false` migration; see {@link applyDetached}. */
+    async revertDetached(record) {
+        await this.runDown(this.rootClient(), this.requireRollback(record));
+        await this.client.transaction(async (transaction) => {
+            await this.acquireMigrationLock(transaction);
+            await this.deleteMigrationRecord(transaction, record.version);
+        }, this.buildTransactionOptions());
+    }
     async revertRecord(transaction, record) {
+        await this.runDown(transaction, this.requireRollback(record));
+        await this.deleteMigrationRecord(transaction, record.version);
+    }
+    requireRollback(record) {
         const migration = this.migrations.find((m) => m.version === record.version);
         if (!migration) {
             throw this.migrationError(`Migration "${record.name}" is recorded as applied but is not registered.`, { metadata: { version: record.version } });
@@ -198,6 +249,9 @@ export class MigrationRunner {
         if (!migration.down) {
             throw this.migrationError(`Migration "${migration.name}" does not define a rollback operation.`, { metadata: { version: migration.version } });
         }
+        return migration;
+    }
+    async runDown(transaction, migration) {
         try {
             await migration.down(transaction);
         }
@@ -207,7 +261,6 @@ export class MigrationRunner {
                 metadata: { version: migration.version, name: migration.name },
             });
         }
-        await this.deleteMigrationRecord(transaction, migration.version);
     }
     computePending(applied) {
         const versions = new Set(applied.map((record) => record.version));
@@ -294,4 +347,3 @@ function hasVersion(records, version) {
 export function createMigrationRunner(client, migrations, options) {
     return new MigrationRunner(client, migrations, options);
 }
-//# sourceMappingURL=migration.runner.js.map

package/dist/migration/migration.types.d.ts

@@ -22,6 +22,18 @@ export interface Migration<TTransaction extends DatabaseTransactionContext = Dat
      * Reverts the migration.
      */
     readonly down?: (database: TTransaction) => Promise<void>;
+    /**
+     * When `false`, `up` and `down` run outside a transaction, on the root
+     * client, which is what statements such as `CREATE INDEX CONCURRENTLY`
+     * or `ALTER TYPE ... ADD VALUE` require. Defaults to `true`.
+     *
+     * The applied check and the history record still happen inside short
+     * transactions under the advisory lock, but the lock is released while
+     * the body runs, so make such a migration idempotent (`IF NOT EXISTS`)
+     * to tolerate a second runner started at the same moment. Requires
+     * `perItemTransaction` (the default); a batch runner refuses it.
+     */
+    readonly transaction?: boolean;
 }
 /**
  * Persisted migration record.
@@ -85,4 +97,3 @@ export interface MigrationRunnerOptions {
      */
     readonly perItemTransaction?: boolean;
 }
-//# sourceMappingURL=migration.types.d.ts.map

package/dist/migration/migration.types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=migration.types.js.map

package/dist/pagination/index.d.ts

@@ -7,4 +7,4 @@ export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, ca
 export { decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, type KeysetPageOptions, type KeysetWhere, } from "./pagination.keyset.js";
 export { KEYSET_BACKWARD_KEY, getKeysetDirection, reverseKeysetSort, keysetFetchSort, type KeysetDirection, } from "./pagination.keysetDirection.js";
 export { createInvalidCursorError, type InvalidCursorReason, } from "./pagination.cursorError.js";
-//# sourceMappingURL=index.d.ts.map
+export { isDateCursorValue, keysetStrictFilter, keysetTieFilter, nextMillisecond, } from "./pagination.keysetValue.js";

package/dist/pagination/index.js

@@ -7,4 +7,4 @@ export { normalizePagination, normalizePage, normalizeLimit, calculateOffset, ca
 export { decodeKeysetCursor, buildKeysetWhere, createKeysetCursor, createKeysetPage, } from "./pagination.keyset.js";
 export { KEYSET_BACKWARD_KEY, getKeysetDirection, reverseKeysetSort, keysetFetchSort, } from "./pagination.keysetDirection.js";
 export { createInvalidCursorError, } from "./pagination.cursorError.js";
-//# sourceMappingURL=index.js.map
+export { isDateCursorValue, keysetStrictFilter, keysetTieFilter, nextMillisecond, } from "./pagination.keysetValue.js";

package/dist/pagination/pagination.core.d.ts

@@ -164,4 +164,3 @@ export declare function decodeCursor<T = unknown>(cursor: string, options?: Deco
  * restricted to the allowed fields.
  */
 export declare function validateCursorPayload(value: unknown, allowedFields: readonly string[]): asserts value is CursorPayload;
-//# sourceMappingURL=pagination.core.d.ts.map

package/dist/pagination/pagination.core.js

@@ -279,4 +279,3 @@ function validateSecret(secret) {
         throw new TypeError("A cursor secret must be a non-empty string.");
     }
 }
-//# sourceMappingURL=pagination.core.js.map

package/dist/pagination/pagination.cursorError.d.ts

@@ -14,4 +14,3 @@ export type InvalidCursorReason = "cursor_required" | "cursor_signature" | "curs
  * failure is kept only as the non-exposed `cause`.
  */
 export declare function createInvalidCursorError(message: string, reason: InvalidCursorReason, cause?: unknown): ValidationError;
-//# sourceMappingURL=pagination.cursorError.d.ts.map

package/dist/pagination/pagination.cursorError.js

@@ -14,4 +14,3 @@ export function createInvalidCursorError(message, reason, cause) {
         ...(cause !== undefined ? { cause } : {}),
     });
 }
-//# sourceMappingURL=pagination.cursorError.js.map

package/dist/pagination/pagination.keyset.d.ts

@@ -49,11 +49,23 @@ export declare function decodeKeysetCursor<TField extends string = string>(curso
  *
  * For a sort of `[a asc, b desc]` the forward result is
  * `OR: [{ a: { gt: A } }, { AND: [{ a: A }, { b: { lt: B } }] }]`.
+ *
+ * A value encoded from a `Date` is compared as its millisecond bucket
+ * (`gte C, lt C + 1ms` for a tie; `lt C` / `gte C + 1ms` for the strict
+ * part), so rows created in the same millisecond as the cursor row on a
+ * microsecond-precision column fall through to the next sort field
+ * instead of being skipped. See `pagination.keysetValue.ts`.
  */
 export declare function buildKeysetWhere<TField extends string = string>(cursor: CursorPayload, sort: readonly SortInput<TField>[]): KeysetWhere;
 /**
  * Derives the cursor payload for a row from the sort fields. A
  * `"backward"` cursor selects the rows before `row` instead of after it.
+ *
+ * `sort` must be the exact sort the page is fetched and decoded with.
+ * `BaseRepository#paginateCursor` appends the id field as a tiebreaker, so
+ * a cursor for a repository page must include it: use
+ * `repository.createCursor(row, { sort })`, which does, rather than this
+ * helper with the bare sort.
  */
 export declare function createKeysetCursor<TField extends string = string>(row: Readonly<Record<string, unknown>>, sort: readonly SortInput<TField>[], secret?: string, direction?: KeysetDirection): string;
 /**
@@ -69,4 +81,3 @@ export declare function createKeysetCursor<TField extends string = string>(row:
  * non-empty page, and `previousCursor` only when more rows precede it.
  */
 export declare function createKeysetPage<TEntity extends Readonly<Record<string, unknown>>, TField extends string = string>(rows: readonly TEntity[], options: KeysetPageOptions<TField>): CursorPaginatedResult<TEntity>;
-//# sourceMappingURL=pagination.keyset.d.ts.map

package/dist/pagination/pagination.keyset.js

@@ -1,6 +1,7 @@
 import { createCursorPaginatedResult, decodeCursor, encodeCursor, normalizeLimit, } from "./pagination.core.js";
 import { createInvalidCursorError } from "./pagination.cursorError.js";
 import { KEYSET_BACKWARD_KEY, getKeysetDirection, reverseKeysetSort, } from "./pagination.keysetDirection.js";
+import { keysetStrictFilter, keysetTieFilter } from "./pagination.keysetValue.js";
 /**
  * Decodes and validates a keyset cursor against the sort definition.
  *
@@ -32,6 +33,12 @@ export function decodeKeysetCursor(cursor, sort, secret) {
  *
  * For a sort of `[a asc, b desc]` the forward result is
  * `OR: [{ a: { gt: A } }, { AND: [{ a: A }, { b: { lt: B } }] }]`.
+ *
+ * A value encoded from a `Date` is compared as its millisecond bucket
+ * (`gte C, lt C + 1ms` for a tie; `lt C` / `gte C + 1ms` for the strict
+ * part), so rows created in the same millisecond as the cursor row on a
+ * microsecond-precision column fall through to the next sort field
+ * instead of being skipped. See `pagination.keysetValue.ts`.
  */
 export function buildKeysetWhere(cursor, sort) {
     validateSort(sort);
@@ -42,10 +49,10 @@ export function buildKeysetWhere(cursor, sort) {
         const conditions = effective
             .slice(0, index)
             .map((previous) => ({
-            [previous.field]: { equals: cursor[previous.field] },
+            [previous.field]: keysetTieFilter(cursor[previous.field]),
         }));
         conditions.push({
-            [entry.field]: { [comparison]: cursor[entry.field] },
+            [entry.field]: keysetStrictFilter(cursor[entry.field], comparison),
         });
         branches.push(conditions.length === 1 ? conditions[0] : { AND: conditions });
     });
@@ -54,6 +61,12 @@ export function buildKeysetWhere(cursor, sort) {
 /**
  * Derives the cursor payload for a row from the sort fields. A
  * `"backward"` cursor selects the rows before `row` instead of after it.
+ *
+ * `sort` must be the exact sort the page is fetched and decoded with.
+ * `BaseRepository#paginateCursor` appends the id field as a tiebreaker, so
+ * a cursor for a repository page must include it: use
+ * `repository.createCursor(row, { sort })`, which does, rather than this
+ * helper with the bare sort.
  */
 export function createKeysetCursor(row, sort, secret, direction = "forward") {
     validateSort(sort);
@@ -133,4 +146,3 @@ function validateSort(sort) {
         seen.add(entry.field);
     }
 }
-//# sourceMappingURL=pagination.keyset.js.map

package/dist/pagination/pagination.keysetDirection.d.ts

@@ -26,4 +26,3 @@ export declare function reverseKeysetSort<TField extends string>(sort: readonly
  * the requested sort going forward, the reversed sort going backward.
  */
 export declare function keysetFetchSort<TField extends string>(sort: readonly SortInput<TField>[], direction: KeysetDirection): readonly SortInput<TField>[];
-//# sourceMappingURL=pagination.keysetDirection.d.ts.map

package/dist/pagination/pagination.keysetDirection.js

@@ -27,4 +27,3 @@ export function reverseKeysetSort(sort) {
 export function keysetFetchSort(sort, direction) {
     return direction === "backward" ? reverseKeysetSort(sort) : sort;
 }
-//# sourceMappingURL=pagination.keysetDirection.js.map

package/dist/pagination/pagination.keysetValue.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Cursor value comparisons for keyset pagination.
+ *
+ * A `Date` is encoded into a cursor as its ISO string, which carries
+ * millisecond precision. PostgreSQL `timestamp`/`timestamptz` columns keep
+ * microseconds unless declared with precision `(3)`, and Prisma hands rows
+ * back as JavaScript `Date`s, so the exact stored value is not available
+ * to the cursor. Comparing `field = C` against such a column matched
+ * nothing and `field < C` skipped every row created in the same
+ * millisecond as the cursor row.
+ *
+ * A date cursor value is therefore compared as its millisecond bucket
+ * `[C, C + 1ms)`: rows outside the bucket are ordered by the strict
+ * comparison, and rows inside it fall through to the next sort field (the
+ * id tiebreaker `paginateCursor` appends). On millisecond-precision
+ * columns this is exactly the old `=`/`<`/`>` comparison.
+ */
+/**
+ * Whether a cursor value was encoded from a `Date` by `createKeysetCursor`.
+ */
+export declare function isDateCursorValue(value: unknown): value is string;
+/**
+ * The ISO string one millisecond after a date cursor value: the exclusive
+ * upper bound of its millisecond bucket.
+ */
+export declare function nextMillisecond(value: string): string;
+/**
+ * The Prisma filter selecting rows that tie with a cursor value on a sort
+ * field: `{ equals }` for ordinary values, the millisecond bucket for dates.
+ */
+export declare function keysetTieFilter(value: unknown): Readonly<Record<string, unknown>>;
+/**
+ * The Prisma filter selecting rows strictly after (`"gt"`) or before
+ * (`"lt"`) a cursor value on a sort field. For a date the boundary is the
+ * whole millisecond bucket: `lt C` below it, `gte C + 1ms` above it.
+ */
+export declare function keysetStrictFilter(value: unknown, comparison: "gt" | "lt"): Readonly<Record<string, unknown>>;

package/dist/pagination/pagination.keysetValue.js

@@ -0,0 +1,55 @@
+/**
+ * Cursor value comparisons for keyset pagination.
+ *
+ * A `Date` is encoded into a cursor as its ISO string, which carries
+ * millisecond precision. PostgreSQL `timestamp`/`timestamptz` columns keep
+ * microseconds unless declared with precision `(3)`, and Prisma hands rows
+ * back as JavaScript `Date`s, so the exact stored value is not available
+ * to the cursor. Comparing `field = C` against such a column matched
+ * nothing and `field < C` skipped every row created in the same
+ * millisecond as the cursor row.
+ *
+ * A date cursor value is therefore compared as its millisecond bucket
+ * `[C, C + 1ms)`: rows outside the bucket are ordered by the strict
+ * comparison, and rows inside it fall through to the next sort field (the
+ * id tiebreaker `paginateCursor` appends). On millisecond-precision
+ * columns this is exactly the old `=`/`<`/`>` comparison.
+ */
+/** Exactly the shape `Date.prototype.toISOString` emits. */
+const ISO_MILLISECOND_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+/**
+ * Whether a cursor value was encoded from a `Date` by `createKeysetCursor`.
+ */
+export function isDateCursorValue(value) {
+    return (typeof value === "string" &&
+        ISO_MILLISECOND_PATTERN.test(value) &&
+        !Number.isNaN(Date.parse(value)));
+}
+/**
+ * The ISO string one millisecond after a date cursor value: the exclusive
+ * upper bound of its millisecond bucket.
+ */
+export function nextMillisecond(value) {
+    return new Date(Date.parse(value) + 1).toISOString();
+}
+/**
+ * The Prisma filter selecting rows that tie with a cursor value on a sort
+ * field: `{ equals }` for ordinary values, the millisecond bucket for dates.
+ */
+export function keysetTieFilter(value) {
+    if (isDateCursorValue(value)) {
+        return { gte: value, lt: nextMillisecond(value) };
+    }
+    return { equals: value };
+}
+/**
+ * The Prisma filter selecting rows strictly after (`"gt"`) or before
+ * (`"lt"`) a cursor value on a sort field. For a date the boundary is the
+ * whole millisecond bucket: `lt C` below it, `gte C + 1ms` above it.
+ */
+export function keysetStrictFilter(value, comparison) {
+    if (isDateCursorValue(value) && comparison === "gt") {
+        return { gte: nextMillisecond(value) };
+    }
+    return { [comparison]: value };
+}

package/dist/queryBuilder/index.d.ts

@@ -8,4 +8,3 @@ export { createQueryBuilder } from "./queryBuilder.factory.js";
 export { toPrismaWhere, toPrismaArgs, toPrismaOrderBy, toPrismaSelect, toPrismaSkipTake, type PrismaWhere, type PrismaQueryArgs, type ToPrismaArgsOptions, } from "./queryBuilder.prisma.js";
 export type { QueryCondition, QueryFilter, QueryOperator, RelationOperator, QueryBuilderState, } from "./queryBuilder.type.js";
 export { equals, notEquals, inList, notInList, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, contains, startsWith, endsWith, isNull, isNotNull, and, or, not, condition, allOf, anyOf, fromObject, dateRange, oneOf, noneOf, optionalEquals, optionalContains, hasConditions, flattenAnd, cloneFilter, between, matchesPattern, isEmpty, isNotEmpty, dateOnly, isBefore, isAfter, isBetween, notCondition, relational, } from "./queryBuilder.filter.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/queryBuilder/index.js

@@ -7,4 +7,3 @@ export { QueryBuilder } from "./queryBuilder.core.js";
 export { createQueryBuilder } from "./queryBuilder.factory.js";
 export { toPrismaWhere, toPrismaArgs, toPrismaOrderBy, toPrismaSelect, toPrismaSkipTake, } from "./queryBuilder.prisma.js";
 export { equals, notEquals, inList, notInList, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, contains, startsWith, endsWith, isNull, isNotNull, and, or, not, condition, allOf, anyOf, fromObject, dateRange, oneOf, noneOf, optionalEquals, optionalContains, hasConditions, flattenAnd, cloneFilter, between, matchesPattern, isEmpty, isNotEmpty, dateOnly, isBefore, isAfter, isBetween, notCondition, relational, } from "./queryBuilder.filter.js";
-//# sourceMappingURL=index.js.map

package/dist/queryBuilder/queryBuilder.core.d.ts

@@ -175,4 +175,3 @@ export declare class QueryBuilder<TField extends string = string> {
      */
     private addCondition;
 }
-//# sourceMappingURL=queryBuilder.core.d.ts.map

package/dist/queryBuilder/queryBuilder.core.js

@@ -417,4 +417,3 @@ function deepFreeze(value) {
     }
     return value;
 }
-//# sourceMappingURL=queryBuilder.core.js.map

package/dist/queryBuilder/queryBuilder.factory.d.ts

@@ -3,4 +3,3 @@ import { QueryBuilder } from "./queryBuilder.core.js";
  * Creates a new query builder.
  */
 export declare function createQueryBuilder<TField extends string = string>(): QueryBuilder<TField>;
-//# sourceMappingURL=queryBuilder.factory.d.ts.map

package/dist/queryBuilder/queryBuilder.factory.js

@@ -5,4 +5,3 @@ import { QueryBuilder } from "./queryBuilder.core.js";
 export function createQueryBuilder() {
     return new QueryBuilder();
 }
-//# sourceMappingURL=queryBuilder.factory.js.map

package/dist/queryBuilder/queryBuilder.filter.d.ts

@@ -167,4 +167,3 @@ export declare function flattenAnd(filter: QueryFilter): QueryCondition[];
  */
 export declare function cloneFilter(filter: QueryFilter): QueryFilter;
 export declare function cloneFilter(filter?: QueryFilter): QueryFilter | undefined;
-//# sourceMappingURL=queryBuilder.filter.d.ts.map

package/dist/queryBuilder/queryBuilder.filter.js

@@ -494,4 +494,3 @@ function validateDate(value, name) {
         throw new TypeError(`Invalid ${name} date.`);
     }
 }
-//# sourceMappingURL=queryBuilder.filter.js.map

package/dist/queryBuilder/queryBuilder.prisma.d.ts

@@ -57,4 +57,3 @@ export declare function toPrismaSkipTake(pagination?: PaginationInput, offset?:
     readonly skip?: number;
     readonly take?: number;
 };
-//# sourceMappingURL=queryBuilder.prisma.d.ts.map

package/dist/queryBuilder/queryBuilder.prisma.js

@@ -225,4 +225,3 @@ function validateFieldName(field) {
         throw new TypeError(`Invalid query field name "${String(field)}".`);
     }
 }
-//# sourceMappingURL=queryBuilder.prisma.js.map

package/dist/queryBuilder/queryBuilder.type.d.ts

@@ -45,4 +45,3 @@ export interface QueryBuilderState<TField extends string = string> {
     readonly select?: readonly TField[];
     readonly include?: readonly RelationInclude[];
 }
-//# sourceMappingURL=queryBuilder.type.d.ts.map

package/dist/queryBuilder/queryBuilder.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=queryBuilder.type.js.map

package/dist/relations/index.d.ts

@@ -4,4 +4,3 @@
  * Entity relation definitions and registry.
  */
 export { oneToOne, oneToMany, manyToOne, manyToMany, includeRelation, includeRelations, RelationRegistry, createRelationRegistry, validateRelation, validateInclude, toPrismaInclude, DEFAULT_INCLUDE_DEPTH, isRelationType, isCollectionRelation, isSingleRelation, type RelationDefinition, type RelationType, type RelationLoadOptions, type RelationInclude, type ToPrismaIncludeOptions, } from "./relations.definition.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/relations/index.js

@@ -4,4 +4,3 @@
  * Entity relation definitions and registry.
  */
 export { oneToOne, oneToMany, manyToOne, manyToMany, includeRelation, includeRelations, RelationRegistry, createRelationRegistry, validateRelation, validateInclude, toPrismaInclude, DEFAULT_INCLUDE_DEPTH, isRelationType, isCollectionRelation, isSingleRelation, } from "./relations.definition.js";
-//# sourceMappingURL=index.js.map

package/dist/relations/relations.definition.d.ts

@@ -181,4 +181,3 @@ export declare function isCollectionRelation(relation: RelationDefinition): bool
  * Returns whether the relation represents a single entity.
  */
 export declare function isSingleRelation(relation: RelationDefinition): boolean;
-//# sourceMappingURL=relations.definition.d.ts.map

package/dist/relations/relations.definition.js

@@ -379,4 +379,3 @@ function validateFieldName(field) {
         throw new TypeError(`Invalid relation field name "${String(field)}".`);
     }
 }
-//# sourceMappingURL=relations.definition.js.map

package/dist/repository/index.d.ts

@@ -3,7 +3,6 @@
  *
  * Generic repository pattern with Prisma delegate support.
  */
-export { BaseRepository, type BaseRepositoryOptions, type SoftDeleteOptions, type CursorQueryOptions, type TransactionClientLike, } from "./repository.base.js";
+export { BaseRepository, type BaseRepositoryOptions, type SoftDeleteOptions, type CreateCursorOptions, type CursorQueryOptions, type TransactionClientLike, } from "./repository.base.js";
 export { type RepositoryDelegate, type RepositoryDelegateOperations, } from "./repository.delegate.js";
 export { mapRepositoryError, isPrismaErrorLike, toDatabaseOperation, toErrorMetadata, createAbortError, createTimeoutError, type RepositoryOperation, type RepositoryErrorContext, type PrismaErrorLike, } from "./repository.errors.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/repository/index.js

@@ -6,4 +6,3 @@
 export { BaseRepository, } from "./repository.base.js";
 export {} from "./repository.delegate.js";
 export { mapRepositoryError, isPrismaErrorLike, toDatabaseOperation, toErrorMetadata, createAbortError, createTimeoutError, } from "./repository.errors.js";
-//# sourceMappingURL=index.js.map

package/dist/repository/repository.base.d.ts

@@ -1,5 +1,6 @@
 import type { DatabaseOperationOptions, PaginatedResult, QueryOptions, Repository, SoftDeletableRepository, SortInput } from "../databaseType/databaseType.type.js";
 import { type CursorPaginatedResult } from "../pagination/pagination.core.js";
+import { type KeysetDirection } from "../pagination/pagination.keysetDirection.js";
 import type { QueryBuilder } from "../queryBuilder/queryBuilder.core.js";
 import type { QueryBuilderState } from "../queryBuilder/queryBuilder.type.js";
 import type { RelationLoadOptions, RelationRegistry } from "../relations/relations.definition.js";
@@ -61,6 +62,22 @@ export interface CursorQueryOptions<TField extends string = string> extends Data
      */
     readonly sort?: readonly SortInput<TField>[];
 }
+/**
+ * Options for {@link BaseRepository.createCursor}.
+ */
+export interface CreateCursorOptions<TField extends string = string> {
+    /**
+     * The sort the page is fetched with, as passed to `paginateCursor`. The
+     * id field is appended as a tiebreaker when absent, exactly as
+     * `paginateCursor` does.
+     */
+    readonly sort?: readonly SortInput<TField>[];
+    /**
+     * `"forward"` (default) selects the rows after `row`; `"backward"` the
+     * rows before it (a `previousCursor`).
+     */
+    readonly direction?: KeysetDirection;
+}
 /**
  * A Prisma transaction client (or any object exposing model delegates).
  */
@@ -133,6 +150,16 @@ export declare abstract class BaseRepository<TEntity, TId = string, TCreateInput
      * before any query runs.
      */
     paginateCursor<TField extends string = string>(filter?: TWhereInput, options?: CursorQueryOptions<TField>): Promise<CursorPaginatedResult<TEntity>>;
+    /**
+     * Builds a cursor positioned at `row` that `paginateCursor` accepts for
+     * the same `sort`: the id tiebreaker is appended and the cursor is
+     * signed with `cursorSecret` when configured.
+     *
+     * `createKeysetCursor(row, sort)` with the bare sort produces a cursor
+     * without the tiebreaker, which `paginateCursor` rejects as missing the
+     * id field.
+     */
+    createCursor<TField extends string = string>(row: TEntity, options?: CreateCursorOptions<TField>): string;
     /**
      * Finds entities from a query builder (or its built state), applying the
      * filter, sort, select, include and pagination it carries.
@@ -234,4 +261,3 @@ export declare abstract class BaseRepository<TEntity, TId = string, TCreateInput
     private buildCursorSort;
     private rebind;
 }
-//# sourceMappingURL=repository.base.d.ts.map

package/dist/repository/repository.base.js

@@ -1,6 +1,6 @@
 import { DatabaseError } from "@zudojs/errors";
 import { createPaginationMeta, normalizeLimit, normalizePage, } from "../pagination/pagination.core.js";
-import { buildKeysetWhere, createKeysetPage, decodeKeysetCursor, } from "../pagination/pagination.keyset.js";
+import { buildKeysetWhere, createKeysetCursor, createKeysetPage, decodeKeysetCursor, } from "../pagination/pagination.keyset.js";
 import { getKeysetDirection, keysetFetchSort, } from "../pagination/pagination.keysetDirection.js";
 import { toPrismaArgs, toPrismaOrderBy, } from "../queryBuilder/queryBuilder.prisma.js";
 import { toDelegateOperations, } from "./repository.delegate.js";
@@ -188,6 +188,18 @@ export class BaseRepository {
             direction,
         });
     }
+    /**
+     * Builds a cursor positioned at `row` that `paginateCursor` accepts for
+     * the same `sort`: the id tiebreaker is appended and the cursor is
+     * signed with `cursorSecret` when configured.
+     *
+     * `createKeysetCursor(row, sort)` with the bare sort produces a cursor
+     * without the tiebreaker, which `paginateCursor` rejects as missing the
+     * id field.
+     */
+    createCursor(row, options) {
+        return createKeysetCursor(row, this.buildCursorSort(options?.sort), this.cursorSecret, options?.direction ?? "forward");
+    }
     /**
      * Finds entities from a query builder (or its built state), applying the
      * filter, sort, select, include and pagination it carries.
@@ -536,4 +548,3 @@ function validateFieldName(field, name) {
 function lowerFirst(value) {
     return value.length === 0 ? value : value[0].toLowerCase() + value.slice(1);
 }
-//# sourceMappingURL=repository.base.js.map

package/dist/repository/repository.delegate.d.ts

@@ -90,4 +90,3 @@ export interface RepositoryDelegateOperations<TEntity, TId = string, TCreateInpu
  * model delegate accepts at runtime.
  */
 export declare function toDelegateOperations<TEntity, TId, TCreateInput, TUpdateInput, TWhereInput>(delegate: RepositoryDelegate<TEntity, TId, TCreateInput, TUpdateInput, TWhereInput>): RepositoryDelegateOperations<TEntity, TId, TCreateInput, TUpdateInput, TWhereInput>;
-//# sourceMappingURL=repository.delegate.d.ts.map

package/dist/repository/repository.delegate.js

@@ -9,4 +9,3 @@
 export function toDelegateOperations(delegate) {
     return delegate;
 }
-//# sourceMappingURL=repository.delegate.js.map

package/dist/repository/repository.errors.d.ts

@@ -40,6 +40,9 @@ export declare function toDatabaseOperation(operation: RepositoryOperation | str
  * - `P2034` serialization failure → `ERR_DATABASE_TRANSACTION` / 409 (retryable)
  * - `P2024` pool timeout → `ERR_DATABASE_TIMEOUT` / 503
  * - `P1xxx` connection failures → `ERR_DATABASE_CONNECTION` / 503
+ * - every other code `normalizeDatabaseError` knows (`P2000` value too
+ *   long / 400, `P2004` constraint / 409, `P2011` null / 400, `P2014`,
+ *   `P2015`, `P2018`, `P2028`) → the same status, code and exposure
  *
  * Existing `DatabaseError`s are returned unchanged.
  */
@@ -57,4 +60,3 @@ export declare function createTimeoutError(context: Omit<RepositoryErrorContext,
  * package accepts.
  */
 export declare function toErrorMetadata(value?: Readonly<Record<string, unknown>>): ErrorMetadata;
-//# sourceMappingURL=repository.errors.d.ts.map