@classytic/repo-core 0.22.0 → 0.23.0

package/dist/repository/types.d.mts

@@ -23,6 +23,20 @@ type FilterInput = Filter | Record<string, unknown>;
  * the session through uses `unknown`; kits narrow at the boundary.
  */
 type RepositorySession = unknown;
+/**
+ * What a transaction callback receives BESIDE the tx-bound repository.
+ *
+ * `session` is the raw driver handle, exposed so work that lives OUTSIDE the
+ * repository can join the same transaction — the canonical consumer is an
+ * outbox writer: `outbox.store(event, { session: uow.session })` commits the
+ * event row atomically with the business write. Present when the driver has a
+ * per-transaction handle (Mongo's ClientSession); connection-bound backends
+ * (SQLite) pass an empty handle — their tx-bound repo IS the only join point.
+ * Kits MUST pass a handle object (possibly empty), never omit the argument.
+ */
+interface TransactionHandle {
+  session?: RepositorySession;
+}
 /**
  * Read-operation options. The index signature is the escape hatch kits use
  * for driver-specific flags (`populate`, `select`, `readPreference`,
@@ -72,6 +86,17 @@ interface QueryOptions {
 interface WriteOptions extends QueryOptions {
   /** Upsert on update/replace. */
   upsert?: boolean;
+  /**
+   * Optimistic-concurrency CAS. When set, the write applies ONLY if the
+   * stored version equals `ifVersion`; on mismatch the kit MUST throw
+   * `VersionConflictError` (`@classytic/repo-core/errors`) — never return
+   * `null`, which means not-found and would invite a blind retry that
+   * clobbers the concurrent write. A successful versioned write increments
+   * the stored version. Requires the `optimisticConcurrency` capability;
+   * kits without it MUST throw on the option rather than ignore it (a
+   * silently dropped guard is the defect, not a degraded mode).
+   */
+  ifVersion?: number;
 }
 /**
  * Options for the optional `findAll` verb.
@@ -1502,6 +1527,15 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    * lives in the kit that knows its driver.
    */
   isDuplicateKeyError?(err: unknown): boolean;
+  /**
+   * Classify an error from a transactional write as a TRANSIENT concurrency
+   * conflict — one the backend expects callers to recover from by re-running
+   * the same work (Mongo `TransientTransactionError` label, PG 40001/40P01,
+   * `SQLITE_BUSY`, Prisma P2034). Consumed by `retryingTransaction`; same
+   * ownership rule as `isDuplicateKeyError` — the kit knows its driver.
+   * Absent = nothing retries (`neverTransient`), the safe default.
+   */
+  isTransientConflictError?(err: unknown): boolean;
   /** Find a single doc by compound filter (used by arc's AccessControl). */
   getOne?(filter: FilterInput, options?: QueryOptions): Promise<TDoc | null>;
   /** Alias many kits expose alongside `getOne`. Arc checks both names. */
@@ -1810,7 +1844,7 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    * // Either both writes commit or neither does.
    * ```
    */
-  withTransaction?<T>(fn: (txRepo: StandardRepo<TDoc>) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
+  withTransaction?<T>(fn: (txRepo: StandardRepo<TDoc>, uow?: TransactionHandle) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
   /**
    * Portable change feed — `for await` over committed mutations:
    *
@@ -1870,4 +1904,4 @@ interface CursorOptions {
   [key: string]: unknown;
 }
 //#endregion
-export { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ChangeEvent, ClaimTransition, ClaimVersionTransition, CursorOptions, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, TransitionArgs, TransitionMachine, UpdateManyResult, WatchOptions, WriteOptions };
+export { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ChangeEvent, ClaimTransition, ClaimVersionTransition, CursorOptions, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, TransactionHandle, TransitionArgs, TransitionMachine, UpdateManyResult, WatchOptions, WriteOptions };

package/dist/testing/conformance.mjs

@@ -1,3 +1,4 @@
+import { isVersionConflictError } from "../errors/conflict.mjs";
 import { and, anyOf as in_, eq, gt, isNull, like, ne, or } from "../filter/builders.mjs";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 //#region src/testing/conformance.ts
@@ -1176,6 +1177,14 @@ function runStandardRepoConformance(harness) {
 				const rows = await ctx.repo.findAll({ name: "tx-rollback" });
 				expect(rows).toHaveLength(0);
 			});
+			it("the callback receives a TransactionHandle — the outbox join point", async () => {
+				let handle = "never-called";
+				await ctx.repo.withTransaction(async (_txRepo, uow) => {
+					handle = uow;
+				});
+				expect(typeof handle).toBe("object");
+				expect(handle).not.toBeNull();
+			});
 			it("reads inside the txRepo see writes inside the same callback", async () => {
 				await ctx.repo.withTransaction(async (txRepo) => {
 					const id = idOf(await txRepo.create(harness.makeDoc({
@@ -1186,6 +1195,60 @@ function runStandardRepoConformance(harness) {
 					expect(back?.name).toBe("tx-read");
 				});
 			});
+			it("declares WHO retries a transient conflict — undeclared ownership stacks retry policies", () => {
+				const caps = ctx.repo.capabilities;
+				expect(caps?.transactionRetry, "a repository exposing withTransaction must declare capabilities.transactionRetry: 'managed' (the kit retries internally, callers invoke it once) or 'caller' (single attempt, an outer envelope owns the loop)").toMatch(/^(managed|caller)$/);
+			});
+			it("nestedTransactions matches what a nested call ACTUALLY does", async () => {
+				const caps = ctx.repo.capabilities;
+				let nestedWorked;
+				try {
+					await ctx.repo.withTransaction(async (txRepo) => {
+						await txRepo.withTransaction?.(async () => {});
+					});
+					nestedWorked = true;
+				} catch {
+					nestedWorked = false;
+				}
+				expect(nestedWorked, `capabilities.nestedTransactions is ${String(caps?.nestedTransactions)} but a nested withTransaction ${nestedWorked ? "succeeded" : "threw"} — the descriptor must describe THIS repository, not the underlying driver`).toBe(caps?.nestedTransactions === true);
+			});
+		});
+		describe.skipIf(!harness.features.optimisticConcurrency)("ifVersion CAS", () => {
+			const versionOf = (doc) => Number(doc[harness.versionField ?? "version"]);
+			it("a matching version applies the write and increments the version", async () => {
+				const created = await ctx.repo.create(harness.makeDoc({
+					name: "cas-ok",
+					email: "cas@x.com"
+				}));
+				const id = idOf(created, harness.idField);
+				const v0 = versionOf(created);
+				const updated = await ctx.repo.update(id, { name: "cas-ok-2" }, { ifVersion: v0 });
+				expect(updated?.name).toBe("cas-ok-2");
+				expect(versionOf(updated)).toBe(v0 + 1);
+			});
+			it("a STALE version throws VersionConflictError — never null", async () => {
+				const created = await ctx.repo.create(harness.makeDoc({
+					name: "cas-stale",
+					email: "stale@x.com"
+				}));
+				const id = idOf(created, harness.idField);
+				const v0 = versionOf(created);
+				await ctx.repo.update(id, { name: "cas-stale-2" }, { ifVersion: v0 });
+				let caught;
+				try {
+					await ctx.repo.update(id, { name: "cas-stale-3" }, { ifVersion: v0 });
+				} catch (e) {
+					caught = e;
+				}
+				expect(isVersionConflictError(caught)).toBe(true);
+				const current = await ctx.repo.getById(id);
+				expect(current?.name).toBe("cas-stale-2");
+			});
+			it("not-found stays null — a missing record is NOT a version conflict", async () => {
+				const ghost = harness.missingId ?? "000000000000000000000000";
+				const out = await ctx.repo.update(ghost, { name: "x" }, { ifVersion: 1 });
+				expect(out).toBeNull();
+			});
 		});
 		describe("purgeByField (tenant cleanup)", () => {
 			const seedTwoTenants = async () => {

package/dist/testing/types.d.mts

@@ -97,6 +97,17 @@ interface ConformanceHarness<TDoc extends ConformanceDoc = ConformanceDoc> {
   idField: string;
   /** Feature support flags — skipped scenarios show as `skipped` in vitest output. */
   features: ConformanceFeatures;
+  /**
+   * Field carrying the optimistic-concurrency version, when the
+   * `optimisticConcurrency` capability is declared. Default `'version'`.
+   */
+  versionField?: string;
+  /**
+   * A syntactically valid id that matches no record — the ifVersion cases
+   * assert not-found stays `null` (never a version conflict). Default is a
+   * Mongo-shaped all-zero ObjectId; SQL/string-id kits supply their own.
+   */
+  missingId?: string;
   /** Create a fresh, isolated repo + cleanup closure. Called per test. */
   setup(): Promise<ConformanceContext<TDoc>>;
   /**

package/package.json

@@ -1,184 +1,184 @@
 {
-	"name": "@classytic/repo-core",
-	"version": "0.22.0",
-	"description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design — no plugins ship here; each kit owns its own.",
-	"type": "module",
-	"sideEffects": false,
-	"files": [
-		"dist",
-		"README.md",
-		"LICENSE",
-		"CHANGELOG.md"
-	],
-	"engines": {
-		"node": ">=22"
-	},
-	"exports": {
-		"./hooks": {
-			"types": "./dist/hooks/index.d.mts",
-			"default": "./dist/hooks/index.mjs"
-		},
-		"./operations": {
-			"types": "./dist/operations/index.d.mts",
-			"default": "./dist/operations/index.mjs"
-		},
-		"./errors": {
-			"types": "./dist/errors/index.d.mts",
-			"default": "./dist/errors/index.mjs"
-		},
-		"./pagination": {
-			"types": "./dist/pagination/index.d.mts",
-			"default": "./dist/pagination/index.mjs"
-		},
-		"./repository": {
-			"types": "./dist/repository/index.d.mts",
-			"default": "./dist/repository/index.mjs"
-		},
-		"./filter": {
-			"types": "./dist/filter/index.d.mts",
-			"default": "./dist/filter/index.mjs"
-		},
-		"./update": {
-			"types": "./dist/update/index.d.mts",
-			"default": "./dist/update/index.mjs"
-		},
-		"./query-parser": {
-			"types": "./dist/query-parser/index.d.mts",
-			"default": "./dist/query-parser/index.mjs"
-		},
-		"./context": {
-			"types": "./dist/context/index.d.mts",
-			"default": "./dist/context/index.mjs"
-		},
-		"./cache": {
-			"types": "./dist/cache/index.d.mts",
-			"default": "./dist/cache/index.mjs"
-		},
-		"./hash": {
-			"types": "./dist/hash/index.d.mts",
-			"default": "./dist/hash/index.mjs"
-		},
-		"./events": {
-			"types": "./dist/events/index.d.mts",
-			"default": "./dist/events/index.mjs"
-		},
-		"./schema": {
-			"types": "./dist/schema/index.d.mts",
-			"default": "./dist/schema/index.mjs"
-		},
-		"./testing": {
-			"types": "./dist/testing/index.d.mts",
-			"default": "./dist/testing/index.mjs"
-		},
-		"./tenant": {
-			"types": "./dist/tenant/index.d.mts",
-			"default": "./dist/tenant/index.mjs"
-		},
-		"./lookup": {
-			"types": "./dist/lookup/index.d.mts",
-			"default": "./dist/lookup/index.mjs"
-		},
-		"./adapter": {
-			"types": "./dist/adapter/index.d.mts",
-			"default": "./dist/adapter/index.mjs"
-		},
-		"./better-auth": {
-			"types": "./dist/better-auth/index.d.mts",
-			"default": "./dist/better-auth/index.mjs"
-		},
-		"./aggregate": {
-			"types": "./dist/aggregate/index.d.mts",
-			"default": "./dist/aggregate/index.mjs"
-		},
-		"./plugins": {
-			"types": "./dist/plugins/index.d.mts",
-			"default": "./dist/plugins/index.mjs"
-		},
-		"./lock": {
-			"types": "./dist/lock/index.d.mts",
-			"default": "./dist/lock/index.mjs"
-		},
-		"./usage": {
-			"types": "./dist/usage/index.d.mts",
-			"default": "./dist/usage/index.mjs"
-		},
-		"./package.json": "./package.json",
-		"./sync": {
-			"types": "./dist/sync/index.d.mts",
-			"default": "./dist/sync/index.mjs"
-		},
-		"./cleanup": {
-			"types": "./dist/cleanup/index.d.mts",
-			"default": "./dist/cleanup/index.mjs"
-		}
-	},
-	"keywords": [
-		"repository",
-		"repository-pattern",
-		"data-access",
-		"hooks",
-		"filter-ir",
-		"pagination",
-		"cursor-pagination",
-		"keyset-pagination",
-		"plugin-based",
-		"driver-agnostic",
-		"typescript",
-		"esm"
-	],
-	"author": "Classytic <classytic.dev@gmail.com> (https://github.com/classytic)",
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/classytic/repo-core.git"
-	},
-	"bugs": {
-		"url": "https://github.com/classytic/repo-core/issues"
-	},
-	"homepage": "https://github.com/classytic/repo-core#readme",
-	"scripts": {
-		"build": "tsdown",
-		"dev": "tsdown --watch",
-		"test": "vitest run --project unit --project integration",
-		"test:unit": "vitest run --project unit",
-		"test:integration": "vitest run --project integration",
-		"test:e2e": "vitest run --project e2e",
-		"test:all": "vitest run",
-		"test:watch": "vitest --project unit --project integration",
-		"bench": "vitest bench --run --project bench",
-		"test:coverage": "vitest run --coverage",
-		"typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
-		"lint": "biome check src tests",
-		"lint:fix": "biome check src tests --write",
-		"format": "biome format src tests --write",
-		"check": "biome ci src tests --diagnostic-level=error",
-		"knip": "knip",
-		"push": "classytic-push",
-		"prepublishOnly": "npm run check && npm run build && npm run typecheck && npm test",
-		"release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
-		"release": "npm run push -- main && npm run release:tag && npm publish",
-		"publish:dry": "npm publish --dry-run --access public",
-		"publish:npm": "npm publish --access public"
-	},
-	"devDependencies": {
-		"@arethetypeswrong/cli": "^0.18.2",
-		"@biomejs/biome": "^2.4.12",
-		"@classytic/dev-tools": "^0.2.0",
-		"@types/node": "^22.0.0",
-		"@vitest/coverage-v8": "^4.1.4",
-		"fast-check": "^4.7.0",
-		"knip": "^6.3.0",
-		"publint": "^0.3.18",
-		"tsdown": "^0.22.14",
-		"typescript": "^7.0.2",
-		"vitest": "^4.1.4"
-	},
-	"peerDependencies": {
-		"vitest": "^3.0.0 || ^4.0.0"
-	},
-	"peerDependenciesMeta": {
-		"vitest": {
-			"optional": true
-		}
-	}
+  "name": "@classytic/repo-core",
+  "version": "0.23.0",
+  "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design — no plugins ship here; each kit owns its own.",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./hooks": {
+      "types": "./dist/hooks/index.d.mts",
+      "default": "./dist/hooks/index.mjs"
+    },
+    "./operations": {
+      "types": "./dist/operations/index.d.mts",
+      "default": "./dist/operations/index.mjs"
+    },
+    "./errors": {
+      "types": "./dist/errors/index.d.mts",
+      "default": "./dist/errors/index.mjs"
+    },
+    "./pagination": {
+      "types": "./dist/pagination/index.d.mts",
+      "default": "./dist/pagination/index.mjs"
+    },
+    "./repository": {
+      "types": "./dist/repository/index.d.mts",
+      "default": "./dist/repository/index.mjs"
+    },
+    "./filter": {
+      "types": "./dist/filter/index.d.mts",
+      "default": "./dist/filter/index.mjs"
+    },
+    "./update": {
+      "types": "./dist/update/index.d.mts",
+      "default": "./dist/update/index.mjs"
+    },
+    "./query-parser": {
+      "types": "./dist/query-parser/index.d.mts",
+      "default": "./dist/query-parser/index.mjs"
+    },
+    "./context": {
+      "types": "./dist/context/index.d.mts",
+      "default": "./dist/context/index.mjs"
+    },
+    "./cache": {
+      "types": "./dist/cache/index.d.mts",
+      "default": "./dist/cache/index.mjs"
+    },
+    "./hash": {
+      "types": "./dist/hash/index.d.mts",
+      "default": "./dist/hash/index.mjs"
+    },
+    "./events": {
+      "types": "./dist/events/index.d.mts",
+      "default": "./dist/events/index.mjs"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.mts",
+      "default": "./dist/schema/index.mjs"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.mts",
+      "default": "./dist/testing/index.mjs"
+    },
+    "./tenant": {
+      "types": "./dist/tenant/index.d.mts",
+      "default": "./dist/tenant/index.mjs"
+    },
+    "./lookup": {
+      "types": "./dist/lookup/index.d.mts",
+      "default": "./dist/lookup/index.mjs"
+    },
+    "./adapter": {
+      "types": "./dist/adapter/index.d.mts",
+      "default": "./dist/adapter/index.mjs"
+    },
+    "./better-auth": {
+      "types": "./dist/better-auth/index.d.mts",
+      "default": "./dist/better-auth/index.mjs"
+    },
+    "./aggregate": {
+      "types": "./dist/aggregate/index.d.mts",
+      "default": "./dist/aggregate/index.mjs"
+    },
+    "./plugins": {
+      "types": "./dist/plugins/index.d.mts",
+      "default": "./dist/plugins/index.mjs"
+    },
+    "./lock": {
+      "types": "./dist/lock/index.d.mts",
+      "default": "./dist/lock/index.mjs"
+    },
+    "./usage": {
+      "types": "./dist/usage/index.d.mts",
+      "default": "./dist/usage/index.mjs"
+    },
+    "./package.json": "./package.json",
+    "./sync": {
+      "types": "./dist/sync/index.d.mts",
+      "default": "./dist/sync/index.mjs"
+    },
+    "./cleanup": {
+      "types": "./dist/cleanup/index.d.mts",
+      "default": "./dist/cleanup/index.mjs"
+    }
+  },
+  "keywords": [
+    "repository",
+    "repository-pattern",
+    "data-access",
+    "hooks",
+    "filter-ir",
+    "pagination",
+    "cursor-pagination",
+    "keyset-pagination",
+    "plugin-based",
+    "driver-agnostic",
+    "typescript",
+    "esm"
+  ],
+  "author": "Classytic <classytic.dev@gmail.com> (https://github.com/classytic)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/classytic/repo-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/classytic/repo-core/issues"
+  },
+  "homepage": "https://github.com/classytic/repo-core#readme",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run --project unit --project integration",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "test:e2e": "vitest run --project e2e",
+    "test:all": "vitest run",
+    "test:watch": "vitest --project unit --project integration",
+    "bench": "vitest bench --run --project bench",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
+    "lint": "biome check src tests",
+    "lint:fix": "biome check src tests --write",
+    "format": "biome format src tests --write",
+    "check": "biome ci src tests --diagnostic-level=error",
+    "knip": "knip",
+    "push": "classytic-push",
+    "prepublishOnly": "npm run check && npm run build && npm run typecheck && npm test",
+    "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
+    "release": "npm run push -- main && npm run release:tag && npm publish",
+    "publish:dry": "npm publish --dry-run --access public",
+    "publish:npm": "npm publish --access public"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@biomejs/biome": "^2.4.12",
+    "@classytic/dev-tools": "^0.2.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.1.4",
+    "fast-check": "^4.7.0",
+    "knip": "^6.3.0",
+    "publint": "^0.3.18",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.4"
+  },
+  "peerDependencies": {
+    "vitest": "^3.0.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  }
 }