@abloatai/ablo 0.26.0 → 0.28.0

package/dist/client/validateAbloOptions.d.ts

@@ -1,22 +1,20 @@
 /**
- * Up-front validation of `AbloOptions`. Returns the first error
- * encountered or null if all checks pass — caller writes the error
- * into `store.syncStatus` so consumers see it through the existing
- * status surface rather than catching it at the call site.
+ * Validates the options passed when constructing a client, before any
+ * connection is attempted. Returns the first problem it finds as an
+ * {@link AbloError}, or null when every check passes. The caller records that
+ * error on the client's sync status, so a misconfiguration surfaces through the
+ * normal status channel rather than throwing at the call site.
  *
- * Extracted from `Ablo.ts` (which was ~2300 LOC of constructor wiring)
- * so the validation rules are readable in isolation. The order of
- * checks matters: missing `url` is checked before identity options
- * because the error messages reference URLs and would mislead if a
- * URL was actually present.
+ * The order of checks matters: a missing `url` is reported before any identity
+ * problem, because the identity error messages mention the URL and would
+ * mislead if the URL were the thing actually missing.
  */
 import { AbloError } from '../errors.js';
 /**
- * Minimal subset of `AbloOptions` the validator actually inspects.
- * Defined here as its own interface so the validator doesn't pull
- * the whole 200+-line `AbloOptions` type — and to avoid a circular
- * import with `Ablo.ts`. Fields are kept structurally identical to
- * `AbloOptions` so a real options object satisfies this shape.
+ * The subset of client options this validator reads. It is declared as its own
+ * interface, structurally compatible with the full options type, so a real
+ * options object satisfies it without the validator having to depend on the
+ * complete type.
  */
 export interface ValidatableAbloOptions {
     readonly schema?: {

package/dist/client/validateAbloOptions.js

@@ -1,14 +1,13 @@
 /**
- * Up-front validation of `AbloOptions`. Returns the first error
- * encountered or null if all checks pass — caller writes the error
- * into `store.syncStatus` so consumers see it through the existing
- * status surface rather than catching it at the call site.
+ * Validates the options passed when constructing a client, before any
+ * connection is attempted. Returns the first problem it finds as an
+ * {@link AbloError}, or null when every check passes. The caller records that
+ * error on the client's sync status, so a misconfiguration surfaces through the
+ * normal status channel rather than throwing at the call site.
  *
- * Extracted from `Ablo.ts` (which was ~2300 LOC of constructor wiring)
- * so the validation rules are readable in isolation. The order of
- * checks matters: missing `url` is checked before identity options
- * because the error messages reference URLs and would mislead if a
- * URL was actually present.
+ * The order of checks matters: a missing `url` is reported before any identity
+ * problem, because the identity error messages mention the URL and would
+ * mislead if the URL were the thing actually missing.
  */
 import { AbloError, AbloValidationError } from '../errors.js';
 export function validateAbloOptions(input) {

package/dist/client/writeOptionsSchema.d.ts

@@ -1,18 +1,19 @@
 /**
- * THE write-options schema — one Zod schema for the write dialect every
- * door speaks (`ablo.<model>.create/update/delete`, `commits.create`, the
- * HTTP model routes). Validated once at each public boundary so a plain-JS
- * caller passing `onStale: 'rejct'` fails loudly at the call site with a
- * typed `AbloValidationError`, not silently (or 400) at the server.
+ * The Zod schema for write options — the settings accepted by every write
+ * entry point, including `ablo.<model>.create/update/delete`, `commits.create`,
+ * and the HTTP write routes. Each of those boundaries validates against this
+ * one schema, so a caller who passes, say, `onStale: 'rejct'` fails right away
+ * with a typed {@link AbloValidationError} at the call site instead of silently
+ * or with a 400 from the server.
  *
- * Mirrors `source/contract.ts`: the schema is the runtime twin of the
- * `MutationOptions` interface, with a compile-time drift guard at the
- * bottom so the two can never silently diverge.
+ * The schema is the runtime counterpart of the {@link MutationOptions}
+ * interface. A compile-time check at the bottom of this file asserts that the
+ * two describe the same shape, so they cannot drift apart.
  *
- * Validation-only by design: callers keep their ORIGINAL options object.
- * Zod's parse output strips unknown keys, and the `claim` slot legally
- * carries live handles (`ClaimHandle` / claim leases) whose
- * `release`/`revoke` functions must survive — so we assert, never replace.
+ * Validation only inspects; it never transforms. Callers keep the exact options
+ * object they passed in. This matters because the `claim` field can hold a live
+ * claim handle whose `release` and `revoke` functions must survive, so the code
+ * asserts the shape rather than replacing the value with a parsed copy.
  */
 import { z } from 'zod';
 export declare const onStaleModeSchema: z.ZodEnum<{
@@ -40,9 +41,10 @@ export declare const writeOptionsSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type WriteOptionsInput = z.infer<typeof writeOptionsSchema>;
 /**
- * Assert a write-options bag against THE schema. Throws a typed
- * `AbloValidationError` (`code: 'write_options_invalid'`, Stripe-style
- * `param` pointing at the offending field) and returns nothing — the
- * caller keeps its original object.
+ * Validates a write-options object against {@link writeOptionsSchema}. On
+ * failure it throws a typed {@link AbloValidationError} — with
+ * `code: 'write_options_invalid'` and a `param` pointing at the offending
+ * field — and on success returns nothing, leaving the caller's original object
+ * untouched. A `null` or `undefined` value passes.
  */
 export declare function assertWriteOptions(value: unknown, context?: string): void;

package/dist/client/writeOptionsSchema.js

@@ -1,24 +1,26 @@
 /**
- * THE write-options schema — one Zod schema for the write dialect every
- * door speaks (`ablo.<model>.create/update/delete`, `commits.create`, the
- * HTTP model routes). Validated once at each public boundary so a plain-JS
- * caller passing `onStale: 'rejct'` fails loudly at the call site with a
- * typed `AbloValidationError`, not silently (or 400) at the server.
+ * The Zod schema for write options — the settings accepted by every write
+ * entry point, including `ablo.<model>.create/update/delete`, `commits.create`,
+ * and the HTTP write routes. Each of those boundaries validates against this
+ * one schema, so a caller who passes, say, `onStale: 'rejct'` fails right away
+ * with a typed {@link AbloValidationError} at the call site instead of silently
+ * or with a 400 from the server.
  *
- * Mirrors `source/contract.ts`: the schema is the runtime twin of the
- * `MutationOptions` interface, with a compile-time drift guard at the
- * bottom so the two can never silently diverge.
+ * The schema is the runtime counterpart of the {@link MutationOptions}
+ * interface. A compile-time check at the bottom of this file asserts that the
+ * two describe the same shape, so they cannot drift apart.
  *
- * Validation-only by design: callers keep their ORIGINAL options object.
- * Zod's parse output strips unknown keys, and the `claim` slot legally
- * carries live handles (`ClaimHandle` / claim leases) whose
- * `release`/`revoke` functions must survive — so we assert, never replace.
+ * Validation only inspects; it never transforms. Callers keep the exact options
+ * object they passed in. This matters because the `claim` field can hold a live
+ * claim handle whose `release` and `revoke` functions must survive, so the code
+ * asserts the shape rather than replacing the value with a parsed copy.
  */
 import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';
 export const onStaleModeSchema = z.enum(['reject', 'overwrite', 'notify']);
 export const writeOptionsSchema = z.object({
-    /** Server-side mutation_log cache key; `null` opts out of retry-safety. */
+    /** Idempotency key the server records in `mutation_log` to make retries
+     *  safe; `null` opts out of that protection. */
     idempotencyKey: z.string().min(1).max(255).nullish(),
     /** Human-readable audit tag, persisted to `mutation_log.label`. */
     label: z.string().max(255).optional(),
@@ -28,17 +30,18 @@ export const writeOptionsSchema = z.object({
     readAt: z.number().int().nonnegative().nullish(),
     /** What the server does when the target moved past `readAt`. */
     onStale: onStaleModeSchema.nullish(),
-    /** Claim/claim attribution — an id, or a live lease handle (loose: the
-     *  handle's `release`/`revoke` functions ride along untouched). */
+    /** The claim this write belongs to — either a claim id, or a live claim
+     *  handle whose `release`/`revoke` functions are preserved untouched. */
     claim: z.union([z.string(), z.looseObject({ id: z.string() })]).nullish(),
-    /** Dormant wire-compat field; always `null` from current clients. */
+    /** Reserved wire-compatibility field; current clients always send `null`. */
     causedByTaskId: z.string().nullish(),
 });
 /**
- * Assert a write-options bag against THE schema. Throws a typed
- * `AbloValidationError` (`code: 'write_options_invalid'`, Stripe-style
- * `param` pointing at the offending field) and returns nothing — the
- * caller keeps its original object.
+ * Validates a write-options object against {@link writeOptionsSchema}. On
+ * failure it throws a typed {@link AbloValidationError} — with
+ * `code: 'write_options_invalid'` and a `param` pointing at the offending
+ * field — and on success returns nothing, leaving the caller's original object
+ * untouched. A `null` or `undefined` value passes.
  */
 export function assertWriteOptions(value, context) {
     if (value == null)

package/dist/client/wsMutationExecutor.d.ts

@@ -1,30 +1,26 @@
 /**
- * The default `MutationExecutor` — sends `{ type: 'commit', ... }` frames over
- * the engine's own WebSocket, resolved lazily at commit time (the WS doesn't
- * exist when the executor is constructed).
- *
- * Extracted from `Ablo.ts`; the factory wires it up with a `getWs` closure
- * over the store holder unless the caller supplies its own executor.
+ * The default {@link MutationExecutor}. It sends each change as a `commit`
+ * frame over the sync engine's own WebSocket, resolving that socket lazily at
+ * commit time because it does not exist yet when the executor is created. A
+ * client wires this up automatically unless you supply your own executor.
  */
 import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
 import type { MutationExecutor, MutationOperation } from '../interfaces/index.js';
 /**
- * Default mutation executor: sends `{ type: 'commit', payload: ... }` over
- * the sync engine's own WebSocket.
+ * Creates the default mutation executor, which sends each change as a `commit`
+ * frame over the sync engine's own WebSocket. The engine owns its socket, so
+ * you pass a URL and credentials rather than transport callbacks.
  *
- * Transport ownership follows the Zero / Liveblocks pattern — the engine
- * owns its socket end-to-end and the executor is internal. Apps pass URLs
- * and auth; they do NOT inject transport callbacks. That's why this
- * factory takes a `getWs` closure instead of a full SyncWebSocket: the WS
- * doesn't exist when the executor is constructed (it's created later in
- * `Ablo` during `BaseSyncedStore` init), so we resolve it
- * lazily at commit time. Same trick Zero uses internally — see
- * `packages/zero-client/src/client/zero.ts` where `Pusher`/`Puller` are
- * constructed before the socket then wired up at connect time.
+ * The factory takes a `getWs` accessor instead of a socket directly because the
+ * socket is created later during client startup and does not exist yet when
+ * this executor is constructed. The accessor is called at commit time to reach
+ * the ready socket.
  *
-     * `options.idempotencyKey` becomes the wire-level `clientTxId` when set,
-     * matching Stripe-style retry semantics. Otherwise the SDK generates one.
-     */
+ * When set, `options.idempotencyKey` is sent as the wire-level `clientTxId`, so
+ * retrying a call with the same key is safe. TransactionQueue always supplies
+ * this key before its first attempt and owns reuse across retries. The fallback
+ * generation below exists only for direct, one-shot executor consumers.
+ */
 export declare function createDefaultMutationExecutor(getWs: () => {
     sendCommit?: (operations: readonly MutationOperation[], clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null) => Promise<{
         lastSyncId: number;

package/dist/client/wsMutationExecutor.js

@@ -1,30 +1,26 @@
 /**
- * The default `MutationExecutor` — sends `{ type: 'commit', ... }` frames over
- * the engine's own WebSocket, resolved lazily at commit time (the WS doesn't
- * exist when the executor is constructed).
- *
- * Extracted from `Ablo.ts`; the factory wires it up with a `getWs` closure
- * over the store holder unless the caller supplies its own executor.
+ * The default {@link MutationExecutor}. It sends each change as a `commit`
+ * frame over the sync engine's own WebSocket, resolving that socket lazily at
+ * commit time because it does not exist yet when the executor is created. A
+ * client wires this up automatically unless you supply your own executor.
  */
 import { AbloError, AbloConnectionError } from '../errors.js';
 // ── Default mutation executor (wire: `commit` frame over WebSocket) ──────
 /**
- * Default mutation executor: sends `{ type: 'commit', payload: ... }` over
- * the sync engine's own WebSocket.
+ * Creates the default mutation executor, which sends each change as a `commit`
+ * frame over the sync engine's own WebSocket. The engine owns its socket, so
+ * you pass a URL and credentials rather than transport callbacks.
  *
- * Transport ownership follows the Zero / Liveblocks pattern — the engine
- * owns its socket end-to-end and the executor is internal. Apps pass URLs
- * and auth; they do NOT inject transport callbacks. That's why this
- * factory takes a `getWs` closure instead of a full SyncWebSocket: the WS
- * doesn't exist when the executor is constructed (it's created later in
- * `Ablo` during `BaseSyncedStore` init), so we resolve it
- * lazily at commit time. Same trick Zero uses internally — see
- * `packages/zero-client/src/client/zero.ts` where `Pusher`/`Puller` are
- * constructed before the socket then wired up at connect time.
+ * The factory takes a `getWs` accessor instead of a socket directly because the
+ * socket is created later during client startup and does not exist yet when
+ * this executor is constructed. The accessor is called at commit time to reach
+ * the ready socket.
  *
-     * `options.idempotencyKey` becomes the wire-level `clientTxId` when set,
-     * matching Stripe-style retry semantics. Otherwise the SDK generates one.
-     */
+ * When set, `options.idempotencyKey` is sent as the wire-level `clientTxId`, so
+ * retrying a call with the same key is safe. TransactionQueue always supplies
+ * this key before its first attempt and owns reuse across retries. The fallback
+ * generation below exists only for direct, one-shot executor consumers.
+ */
 export function createDefaultMutationExecutor(getWs) {
     async function commit(operations, options) {
         const ws = getWs();
@@ -41,9 +37,8 @@ export function createDefaultMutationExecutor(getWs) {
             options?.causedByTaskId, options?.reads);
         }
         catch (err) {
-            // Wrap transport-level failures as connection errors so the
-            // TransactionQueue's retry classifier treats them as transient
-            // (matches the old HTTP path's network-error handling).
+            // Wrap transport-level failures as connection errors so the transaction
+            // queue's retry classifier treats them as transient and retries them.
             if (err instanceof AbloError)
                 throw err;
             if (err instanceof Error) {