@classytic/repo-core 0.27.0 → 0.28.0

package/dist/cache/engine.mjs

@@ -140,7 +140,9 @@ var CacheEngine = class {
 			status: "wait",
 			promise: existing.promise
 		};
-		this.pending.set(key, Promise.withResolvers());
+		const deferred = Promise.withResolvers();
+		deferred.promise.catch(() => {});
+		this.pending.set(key, deferred);
 		return { status: "claimed" };
 	}
 	/** Resolve an in-flight claim with the fresh result + clear it. */

package/dist/cache/plugin/context.mjs

@@ -52,7 +52,9 @@ const DEFAULT_SHAPE_KEYS_BY_OP = Object.freeze({
 		"lean",
 		"page",
 		"limit",
-		"after"
+		"after",
+		"countStrategy",
+		"countLimit"
 	],
 	count: ["filter", "filters"],
 	exists: ["filter", "filters"],

package/dist/pagination/keyset.mjs

@@ -38,8 +38,6 @@ function validateKeysetSort(sort, allowedPrimaryFields) {
 	if (allowedPrimaryFields && allowedPrimaryFields.length > 0) {
 		for (const key of nonIdKeys) if (!allowedPrimaryFields.includes(key)) throw new Error(`Keyset sort field "${key}" is not in the strictKeysetSortFields allowlist. Allowed: ${allowedPrimaryFields.join(", ")}. (Protects against lossy null/non-null keyset boundaries.)`);
 	}
-	for (const key of nonIdKeys) if (sort[key] !== primaryDirection) throw new Error("All sort fields must share the same direction for keyset pagination");
-	if (keys.includes("_id") && sort["_id"] !== primaryDirection) throw new Error("_id direction must match primary field direction");
 	if (!keys.includes("_id")) return normalizeSort({
 		...sort,
 		_id: primaryDirection

package/dist/pagination/types.d.mts

@@ -124,6 +124,18 @@ interface KeysetPaginationResultCore<TDoc> {
   hasMore: boolean;
   /** Cursor token for the next page, or `null` when there is none. */
   next: string | null;
+  /**
+   * Cursor token for the PREVIOUS page, or `null` when this is the first.
+   * Feed it back as `before` to walk backwards.
+   *
+   * Optional so a kit that only pages forward is unchanged — but `undefined`
+   * means "this kit does not answer the question", NOT "there is no previous
+   * page". A UI must read {@link hasPrev} to decide whether to offer the
+   * control, and treat absent as unknown rather than as `false`.
+   */
+  prev?: string | null;
+  /** Whether a previous page exists. Absent when the kit does not track it. */
+  hasPrev?: boolean;
 }
 /**
  * Keyset-paginated result envelope.

package/dist/repository/index.d.mts

@@ -1,7 +1,7 @@
 import { LookupPopulateOptions, LookupPopulateResult, LookupRow, LookupSpec } from "../lookup/types.mjs";
 import { UpdateInput } from "../update/types.mjs";
 import { nestDottedKeys, nestDottedKeysAll } from "./agg-output.mjs";
-import { RetryPolicy, throwIfAborted, withRetry } from "./resilience.mjs";
+import { RetryPolicy, isTransientError, throwIfAborted, withRetry } from "./resilience.mjs";
 import { ArchiveOptions, ArchivePort, ArchiveProgress, ArchiveResult, ArchiveSink, runChunkedArchive } from "./archive.mjs";
 import { PLUGIN_ORDER_CONSTRAINTS, Plugin, PluginFunction, PluginType, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase, RepositoryBaseOptions } from "./base.mjs";
@@ -12,4 +12,4 @@ import { STANDARD_REPO_OPTION_KEYS, StandardRepoOptionKey } from "./options.mjs"
 import { PurgePort, WritingPurgeStrategy, runChunkedPurge } from "./purge.mjs";
 import { ReadOnlyRepoOptions, ReadOnlyRepositoryError, asReadOnlyRepo, isReadOnlyRepo } from "./read-only.mjs";
 import { RetryingTransactionOptions, retryingTransaction } from "./retrying-transaction.mjs";
-export { type AggCacheOptions, type AggDateBucket, type AggDateBucketInterval, type AggDateBucketUnit, type AggExecutionHints, type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type AggTopN, type AggTopNTies, type AggregateOpsSupport, type ArchiveOptions, type ArchivePort, type ArchiveProgress, type ArchiveResult, type ArchiveSink, type BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ChangeEvent, type ClaimTransition, type ClaimVersionTransition, type CursorOptions, type DeleteManyResult, type DeleteOptions, type DeleteResult, type DistributionConfig, type DistributionMissHandler, type FilterInput, type FindAllOptions, type FindOneAndUpdateOptions, type InferDoc, type KeysetAggPaginationResult, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type PurgePort, type QueryOptions, type ReadOnlyRepoOptions, ReadOnlyRepositoryError, type RepoCapabilities, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type RetryPolicy, type RetryingTransactionOptions, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type TenantPurgeOptions, type TenantPurgeProgress, type TenantPurgeResult, type TenantPurgeStrategy, type TransactionHandle, type TransitionArgs, type TransitionMachine, type UpdateInput, type UpdateManyResult, type WatchOptions, type WriteOptions, type WritingPurgeStrategy, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };
+export { type AggCacheOptions, type AggDateBucket, type AggDateBucketInterval, type AggDateBucketUnit, type AggExecutionHints, type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type AggTopN, type AggTopNTies, type AggregateOpsSupport, type ArchiveOptions, type ArchivePort, type ArchiveProgress, type ArchiveResult, type ArchiveSink, type BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ChangeEvent, type ClaimTransition, type ClaimVersionTransition, type CursorOptions, type DeleteManyResult, type DeleteOptions, type DeleteResult, type DistributionConfig, type DistributionMissHandler, type FilterInput, type FindAllOptions, type FindOneAndUpdateOptions, type InferDoc, type KeysetAggPaginationResult, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type PurgePort, type QueryOptions, type ReadOnlyRepoOptions, ReadOnlyRepositoryError, type RepoCapabilities, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type RetryPolicy, type RetryingTransactionOptions, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type TenantPurgeOptions, type TenantPurgeProgress, type TenantPurgeResult, type TenantPurgeStrategy, type TransactionHandle, type TransitionArgs, type TransitionMachine, type UpdateInput, type UpdateManyResult, type WatchOptions, type WriteOptions, type WritingPurgeStrategy, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, isTransientError, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };

package/dist/repository/index.mjs

@@ -1,5 +1,5 @@
 import { nestDottedKeys, nestDottedKeysAll } from "./agg-output.mjs";
-import { throwIfAborted, withRetry } from "./resilience.mjs";
+import { isTransientError, throwIfAborted, withRetry } from "./resilience.mjs";
 import { runChunkedArchive } from "./archive.mjs";
 import { PLUGIN_ORDER_CONSTRAINTS, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase } from "./base.mjs";
@@ -8,4 +8,4 @@ import { STANDARD_REPO_OPTION_KEYS } from "./options.mjs";
 import { runChunkedPurge } from "./purge.mjs";
 import { ReadOnlyRepositoryError, asReadOnlyRepo, isReadOnlyRepo } from "./read-only.mjs";
 import { retryingTransaction } from "./retrying-transaction.mjs";
-export { PLUGIN_ORDER_CONSTRAINTS, ReadOnlyRepositoryError, RepositoryBase, STANDARD_REPO_OPTION_KEYS, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };
+export { PLUGIN_ORDER_CONSTRAINTS, ReadOnlyRepositoryError, RepositoryBase, STANDARD_REPO_OPTION_KEYS, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, isTransientError, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };

package/dist/repository/resilience.d.mts

@@ -9,24 +9,26 @@
  * never drifts between call sites.
  */
 /**
- * Retry policy for transient failures (network blips, write conflicts,
- * busy-locks, connection resets).
+ * The default `shouldRetry`: retry a failure that may not have happened, never
+ * one that definitely did.
  *
- * **Don't retry blindly.** Validation errors, schema errors, permission
- * errors are NOT transient — retrying just delays the same failure.
- * Mongo `WriteConflict`, SQLite `SQLITE_BUSY`, `ECONNRESET` ARE transient
- * — backoff + retry recovers. Pass `shouldRetry` to narrow when you know
- * your driver's error taxonomy:
+ * This used to be `() => true`, with a comment conceding it was unsafe and
+ * asking callers to pass their own. That is a documented hazard rather than a
+ * fence — a policy set for network blips also re-ran the write on a duplicate
+ * key, a validation failure and a permission denial, three times, with backoff.
+ * For a non-idempotent write that is not a slow failure, it is a double write.
  *
- * ```ts
- * retryPolicy: {
- *   maxAttempts: 3,         // default 3 when block present
- *   baseDelayMs: 100,       // exponential: 100ms, 200ms, 400ms
- *   shouldRetry: (err) =>
- *     /WriteConflict|SQLITE_BUSY|ECONNRESET/i.test(String(err)),
- * }
- * ```
+ * Retried: replica-set failover, write conflicts, lock timeouts, socket errors
+ * — states where the outcome is genuinely unknown.
+ *
+ * NOT retried: anything the server answered deterministically. A 4xx-shaped
+ * `statusCode` is treated as final, since repo-core's own `HttpError` carries
+ * one and every kit maps validation/permission failures onto it.
+ *
+ * Pass `shouldRetry: () => true` to restore the old behaviour explicitly — the
+ * point is that it is now a choice someone made, not a default they inherited.
  */
+declare function isTransientError(err: unknown): boolean;
 interface RetryPolicy {
   /** Max attempts (including the first try). Default 3 when a policy is present. */
   maxAttempts?: number;
@@ -42,10 +44,13 @@ interface RetryPolicy {
    */
   jitter?: boolean;
   /**
-   * Decide whether a given error is transient. Default: retry every error —
-   * kept for back-compat, but UNSAFE as a shared default (it re-runs side
-   * effects on deterministic failures); pass an explicit predicate.
-   * `retryingTransaction` always does.
+   * Decide whether a given error is transient.
+   *
+   * Defaults to {@link isTransientError}: retry a failure that MAY not have
+   * happened (failover, write conflict, socket error), never one that
+   * definitely did (duplicate key, validation, permission). Pass
+   * `() => true` to retry everything — allowed, but as a decision rather
+   * than an inheritance.
    */
   shouldRetry?: (err: unknown, attempt: number) => boolean;
 }
@@ -66,4 +71,4 @@ declare function withRetry<T>(fn: () => Promise<T>, policy: RetryPolicy | undefi
  */
 declare function throwIfAborted(signal: AbortSignal | undefined): void;
 //#endregion
-export { RetryPolicy, throwIfAborted, withRetry };
+export { RetryPolicy, isTransientError, throwIfAborted, withRetry };

package/dist/repository/resilience.mjs

@@ -1,5 +1,69 @@
 //#region src/repository/resilience.ts
 /**
+* Resilience primitives — the single retry/abort contract every kit and
+* every chunked orchestrator (purge, batch imports, outbox relays) uses.
+*
+* One `RetryPolicy` shape across the contract: `QueryOptions.retryPolicy`,
+* `TenantPurgeOptions.retry`, and any kit-internal retry loop all accept
+* the same three knobs. One `withRetry` implementation so backoff math
+* never drifts between call sites.
+*/
+/**
+* Retry policy for transient failures (network blips, write conflicts,
+* busy-locks, connection resets).
+*
+* **Don't retry blindly.** Validation errors, schema errors, permission
+* errors are NOT transient — retrying just delays the same failure.
+* Mongo `WriteConflict`, SQLite `SQLITE_BUSY`, `ECONNRESET` ARE transient
+* — backoff + retry recovers. Pass `shouldRetry` to narrow when you know
+* your driver's error taxonomy:
+*
+* ```ts
+* retryPolicy: {
+*   maxAttempts: 3,         // default 3 when block present
+*   baseDelayMs: 100,       // exponential: 100ms, 200ms, 400ms
+*   shouldRetry: (err) =>
+*     /WriteConflict|SQLITE_BUSY|ECONNRESET/i.test(String(err)),
+* }
+* ```
+*/
+/**
+* Error labels and names that mean "the operation may not have run — running
+* it again is safe". Duck-typed so `repo-core` stays driver-free: MongoDB sets
+* these labels, and other drivers surface the same idea under these names.
+*/
+const TRANSIENT_LABELS = ["RetryableWriteError", "TransientTransactionError"];
+const TRANSIENT_PATTERN = /WriteConflict|LockTimeout|NotWritablePrimary|NotPrimary|PrimarySteppedDown|InterruptedDueToReplStateChange|ShutdownInProgress|HostUnreachable|HostNotFound|NetworkTimeout|SocketException|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|SQLITE_BUSY|SQLITE_LOCKED|MongoNetworkError/i;
+/**
+* The default `shouldRetry`: retry a failure that may not have happened, never
+* one that definitely did.
+*
+* This used to be `() => true`, with a comment conceding it was unsafe and
+* asking callers to pass their own. That is a documented hazard rather than a
+* fence — a policy set for network blips also re-ran the write on a duplicate
+* key, a validation failure and a permission denial, three times, with backoff.
+* For a non-idempotent write that is not a slow failure, it is a double write.
+*
+* Retried: replica-set failover, write conflicts, lock timeouts, socket errors
+* — states where the outcome is genuinely unknown.
+*
+* NOT retried: anything the server answered deterministically. A 4xx-shaped
+* `statusCode` is treated as final, since repo-core's own `HttpError` carries
+* one and every kit maps validation/permission failures onto it.
+*
+* Pass `shouldRetry: () => true` to restore the old behaviour explicitly — the
+* point is that it is now a choice someone made, not a default they inherited.
+*/
+function isTransientError(err) {
+	if (err === null || typeof err !== "object") return false;
+	const e = err;
+	if (typeof e.hasErrorLabel === "function") for (const label of TRANSIENT_LABELS) try {
+		if (e.hasErrorLabel(label)) return true;
+	} catch {}
+	if (typeof e.statusCode === "number" && e.statusCode >= 400 && e.statusCode < 500) return false;
+	return TRANSIENT_PATTERN.test(`${String(e.name ?? "")} ${String(e.codeName ?? "")} ${String(e.code ?? "")} ${String(e.message ?? "")}`);
+}
+/**
 * Abortable sleep. A plain `setTimeout` promise holds the process through an
 * abort — a cancelled request would silently wait out its full backoff before
 * noticing. Listener is removed on the timer path so repeated retries don't
@@ -31,7 +95,7 @@ async function withRetry(fn, policy, signal) {
 	if (!policy) return fn();
 	const maxAttempts = policy.maxAttempts ?? 3;
 	const baseDelayMs = policy.baseDelayMs ?? 100;
-	const shouldRetry = policy.shouldRetry ?? (() => true);
+	const shouldRetry = policy.shouldRetry ?? isTransientError;
 	let lastErr;
 	for (let attempt = 0; attempt < maxAttempts; attempt++) {
 		signal?.throwIfAborted();
@@ -59,4 +123,4 @@ function throwIfAborted(signal) {
 	signal?.throwIfAborted();
 }
 //#endregion
-export { throwIfAborted, withRetry };
+export { isTransientError, throwIfAborted, withRetry };

package/dist/repository/types.d.mts

@@ -623,7 +623,37 @@ type AggMeasure = {
   op: 'count';
   field?: string;
   where?: FilterInput;
-} | {
+} |
+/**
+ * Exact distinct count. **Bounded by group memory — see the ceiling below
+ * before using it on a high-cardinality field.**
+ *
+ * It is computed by accumulating the distinct values themselves and taking
+ * the size, so every distinct value in a group is held in that group's
+ * accumulator at once. Cheap for `countDistinct` over a status or a region;
+ * expensive over a user id, an email, or a session token, where the
+ * accumulator grows with the data rather than with the answer.
+ *
+ * MongoDB caps a single group accumulator at 100MB. Past that the pipeline
+ * fails — loudly, which is the right outcome, but it fails at the size the
+ * data reaches rather than at the size anyone planned for.
+ *
+ * Mitigations, in the order worth trying:
+ *   1. narrow the groups (`where`, a tighter `groupBy`) so each accumulator
+ *      holds less;
+ *   2. pass `allowDiskUse` so the stage may spill instead of failing — it
+ *      makes the query slow rather than impossible, and does NOT make every
+ *      accumulator shape safe;
+ *   3. for genuinely unbounded cardinality, count distinct in its own
+ *      request grouped by `(group keys, the distinct field)` and sum the
+ *      rows — one pass more, no accumulator growth.
+ *
+ * There is deliberately no approximate mode: a distinct count that is
+ * quietly within a few percent is exactly the plausible-looking wrong number
+ * this contract exists to avoid. If an estimate is acceptable, the caller
+ * should ask for one explicitly rather than inherit it.
+ */
+{
   op: 'countDistinct';
   field: string;
   where?: FilterInput;
@@ -1084,6 +1114,32 @@ interface AggRequest {
    * each partition).
    */
   topN?: AggTopN;
+  /**
+   * How `countDistinct` is computed.
+   *
+   * - **`'accumulator'`** (default) — collect the distinct values, take the
+   *   size. One pass, and the cheapest thing there is while a group's distinct
+   *   values fit in memory. They are held in that group's accumulator at once,
+   *   so the cost grows with the DATA, not with the answer: fine over a status
+   *   or a region, and a 100MB accumulator failure over a user id or an email.
+   *
+   * - **`'grouped'`** — pre-group by the distinct field so each distinct value
+   *   becomes a row, then count rows. One extra `$group`, and nothing
+   *   accumulates: cardinality stops being a memory question. Slower on small
+   *   groups, which is why it is not the default.
+   *
+   * Results are IDENTICAL either way, including the parts that are easy to get
+   * wrong — a missing field is not a distinct value, an explicit `null` is, and
+   * `where` excludes rows from the count without excluding them from the other
+   * measures. `tests/integration/countdistinct-strategies.test.ts` asserts the
+   * two strategies agree row for row rather than asserting expected numbers,
+   * because a strategy that is merely self-consistent is the failure mode.
+   *
+   * `'grouped'` REFUSES a measure set it cannot re-aggregate (`avg`,
+   * `percentile`, `stddev`, or a second `countDistinct`) instead of returning a
+   * plausible wrong number — see the error for the alternatives.
+   */
+  countDistinctStrategy?: 'accumulator' | 'grouped';
   /**
    * Driver-tunable performance knobs (allowDiskUse, maxTimeMs,
    * indexHint). See `AggExecutionHints` for the per-kit support
@@ -1879,6 +1935,14 @@ interface ChangeEvent<TDoc = unknown> {
   doc?: TDoc;
   /** Commit timestamp as reported by the backend. */
   timestamp: Date;
+  /**
+   * Resume token for THIS event (kit-specific opaque shape — Mongo's
+   * change-document `_id`). Persist the last one you finished processing
+   * and hand it back as `WatchOptions.resumeAfter` / `startAfter` to
+   * continue from that point across restarts. Absent on backends whose
+   * feed is not resumable.
+   */
+  resumeToken?: unknown;
 }
 /** Options for `StandardRepo.watch()`. */
 interface WatchOptions {
@@ -1890,6 +1954,40 @@ interface WatchOptions {
    * for at-least-once consumption across restarts.
    */
   resumeAfter?: unknown;
+  /**
+   * Like `resumeAfter`, but also resumes past an invalidate event (Mongo
+   * `startAfter` — the token of the invalidate itself). Mutually exclusive
+   * with `resumeAfter`; kits reject a call that sets both.
+   */
+  startAfter?: unknown;
+  /**
+   * Ceiling on events held between the stream and a slower consumer.
+   * Default 1024. `0` disables the bound; any other non-positive-integer
+   * (negative, fractional, `Infinity`, `NaN`) is REFUSED rather than treated
+   * as unbounded — silently removing the ceiling is the failure this option
+   * exists to prevent.
+   *
+   * A change feed has no backpressure: the server pushes, and a kit bridging
+   * it into an async iterator buffers whatever the consumer has not reached.
+   * An unbounded buffer therefore turns a consumer that is merely SLOWER than
+   * the write rate into unbounded memory growth — and the symptom is an OOM
+   * far from the cause.
+   *
+   * Overflow ends the iterator with an error carrying `resumeToken` — the last
+   * event the consumer ACKNOWLEDGED, meaning the last one it came back from.
+   * Deliberately not the last DELIVERED event: resuming past one the consumer
+   * was still processing drops it. The error also carries `deliveredToken` for
+   * diagnostics; resuming from that reintroduces the loss.
+   *
+   * It never drops events either way. A change feed silently missing a delete
+   * is the kind of wrong that surfaces as a reconciliation mystery months
+   * later, so the asymmetry is chosen on purpose: redelivering costs a
+   * duplicate, skipping costs a lost write.
+   *
+   * A change stream is an INGESTION mechanism, not a durable queue. Consumers
+   * that must not miss events persist the resume token and stay idempotent.
+   */
+  maxBufferedEvents?: number;
 }
 /**
  * Options for `StandardRepo.cursor()` streaming reads. The open index

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.27.0",
+  "version": "0.28.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,