@abloatai/transaction 0.37.0

package/src/utils/asyncIterator.ts

@@ -0,0 +1,141 @@
+/**
+ * Turns a callback-based subscription into an async iterable that yields the
+ * latest snapshot each time the source changes. You supply two functions:
+ * `subscribe(listener)`, which registers your listener and returns a teardown
+ * function, and `getSnapshot()`, which reads the current value. On every change
+ * notification the iterator calls `getSnapshot()` and hands the result to the
+ * consumer's `for await` loop; when the loop ends, the iterator runs the
+ * teardown function.
+ *
+ * Because each notification yields the current snapshot rather than a specific
+ * event, bursts coalesce harmlessly — a consumer that falls behind still ends up
+ * with the freshest value. The queue is unbounded, so a consumer that never
+ * advances lets memory grow without limit. When individual events matter and
+ * must not be dropped, use {@link asyncIteratorFromEvents} instead.
+ *
+ * Each call to the factory creates an independent iterator with its own
+ * subscription. Two `for await` loops over the same source each observe every
+ * change; they do not take values from one another.
+ */
+/**
+ * Turns a callback-based subscription into an async iterable that yields each
+ * discrete event, in order, with none dropped. You supply a single
+ * `subscribe(push)` function: it registers your producer and returns a teardown
+ * function, and your producer calls `push(value)` once per event. The consumer's
+ * `for await` loop receives every pushed value.
+ *
+ * This is the counterpart to {@link asyncIteratorFrom}. Reach for that one when
+ * you only need the latest state and coalescing bursts is fine; reach for this
+ * one when every event is significant — for example a stream of change deltas
+ * where skipping one would lose data. The queue is unbounded, so a consumer that
+ * stops advancing lets memory grow without limit.
+ */
+export function asyncIteratorFromEvents<T>(
+  subscribe: (push: (value: T) => void) => () => void,
+): AsyncIterableIterator<T> {
+  const queue: T[] = [];
+  const resolvers: ((result: IteratorResult<T>) => void)[] = [];
+  let done = false;
+
+  const push = (value: T) => {
+    if (done) return;
+    const resolver = resolvers.shift();
+    if (resolver) {
+      resolver({ value, done: false });
+    } else {
+      queue.push(value);
+    }
+  };
+
+  const unsubscribe = subscribe(push);
+
+  const finish = (): IteratorResult<T> => {
+    done = true;
+    unsubscribe();
+    for (const r of resolvers) r({ value: undefined, done: true });
+    resolvers.length = 0;
+    queue.length = 0;
+    return { value: undefined, done: true };
+  };
+
+  return {
+    async next(): Promise<IteratorResult<T>> {
+      if (done) return { value: undefined, done: true };
+      if (queue.length > 0) {
+        return { value: queue.shift()!, done: false };
+      }
+      return new Promise<IteratorResult<T>>((resolve) => {
+        resolvers.push(resolve);
+      });
+    },
+    async return(): Promise<IteratorResult<T>> {
+      return finish();
+    },
+    async throw(err): Promise<IteratorResult<T>> {
+      finish();
+      throw err;
+    },
+    [Symbol.asyncIterator]() {
+      return this;
+    },
+  };
+}
+
+export function asyncIteratorFrom<T>(
+  subscribe: (listener: () => void) => () => void,
+  getSnapshot: () => T,
+): AsyncIterableIterator<T> {
+  const queue: T[] = [];
+  // Pending `next()` callers waiting for a value. Empty when the
+  // consumer is keeping up; holds 0-or-1 resolver when they're
+  // awaiting. We never hold more than one at a time — a consumer
+  // that calls `next()` twice without awaiting the first breaks
+  // the async-iterator contract.
+  const resolvers: ((result: IteratorResult<T>) => void)[] = [];
+  let done = false;
+
+  const push = () => {
+    if (done) return;
+    const value = getSnapshot();
+    const resolver = resolvers.shift();
+    if (resolver) {
+      resolver({ value, done: false });
+    } else {
+      queue.push(value);
+    }
+  };
+
+  const unsubscribe = subscribe(push);
+
+  const finish = (): IteratorResult<T> => {
+    done = true;
+    unsubscribe();
+    // Resolve any dangling readers so their awaits don't leak.
+    for (const r of resolvers) r({ value: undefined, done: true });
+    resolvers.length = 0;
+    queue.length = 0;
+    return { value: undefined, done: true };
+  };
+
+  return {
+    async next(): Promise<IteratorResult<T>> {
+      if (done) return { value: undefined, done: true };
+      if (queue.length > 0) {
+        return { value: queue.shift()!, done: false };
+      }
+      return new Promise<IteratorResult<T>>((resolve) => {
+        resolvers.push(resolve);
+      });
+    },
+    async return(): Promise<IteratorResult<T>> {
+      return finish();
+    },
+    async throw(err): Promise<IteratorResult<T>> {
+      finish();
+      throw err;
+    },
+    [Symbol.asyncIterator]() {
+      return this;
+    },
+  };
+}

package/src/utils/duration.ts

@@ -0,0 +1,88 @@
+/**
+ * Parses a duration into milliseconds. A duration is either a number of seconds
+ * or a string with a unit suffix — milliseconds, seconds, minutes, or hours:
+ *
+ *   - `'500ms'` → 500 ms
+ *   - `'30s'`   → 30 000 ms
+ *   - `'3m'`    → 180 000 ms
+ *   - `'24h'`   → 86 400 000 ms
+ *
+ * A bare number is interpreted as seconds rather than milliseconds, matching the
+ * `ttlSeconds` fields used throughout the SDK, so a numeric caller and a string
+ * caller can pass the same field interchangeably. {@link toMs} returns
+ * milliseconds; {@link toSeconds} returns whole seconds.
+ */
+
+import { z } from 'zod';
+import { AbloValidationError } from '../errors.js';
+
+export type Duration = number | `${number}ms` | `${number}s` | `${number}m` | `${number}h`;
+
+const PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/;
+
+/**
+ * The same grammar as a boundary schema, so a duration crossing the wire is
+ * checked against the parser that will read it rather than against a second
+ * description of it.
+ *
+ * The regex is shared with {@link toMs} deliberately: `z.toJSONSchema` emits it
+ * as a `pattern`, which is how a non-TypeScript caller learns the grammar at
+ * all. A union of `number | string` — which is what this used to be on the
+ * claim bodies — publishes as "some number or some string" and leaves the units
+ * to be guessed.
+ */
+export const durationSchema = z.union([
+  z.number().positive(),
+  z.string().regex(PATTERN, {
+    message: 'expected a duration such as "500ms", "30s", "3m" or "24h"',
+  }),
+]);
+
+const UNIT_MS: Record<'ms' | 's' | 'm' | 'h', number> = {
+  ms: 1,
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+};
+
+/**
+ * Parses a duration and returns the equivalent number of milliseconds. Accepts
+ * either a bare number, interpreted as seconds, or a unit-suffixed string such
+ * as `'500ms'`, `'30s'`, `'3m'`, or `'24h'`. Throws an
+ * {@link AbloValidationError} with code `duration_invalid` when a string does
+ * not match a supported unit.
+ *
+ * Two doors, one implementation. {@link toMs} takes the narrow {@link Duration}
+ * template type, so an SDK caller writing a literal gets the unit checked at
+ * compile time. {@link parseDurationMs} takes the widened `string | number` that
+ * {@link durationSchema} infers — the shape a value has after it crossed the
+ * wire and was validated at the boundary. Neither is a cast of the other, and
+ * neither carries its own copy of the grammar.
+ */
+export function toMs(input: Duration): number {
+  return parseDurationMs(input);
+}
+
+/**
+ * {@link toMs} for a value that arrived over the wire, where the type system
+ * knows only `string | number` because that is what the boundary schema infers.
+ */
+export function parseDurationMs(input: string | number): number {
+  if (typeof input === 'number') return input * 1_000;
+  const match = PATTERN.exec(input);
+  if (!match) {
+    throw new AbloValidationError(
+      `Invalid duration "${input}" — expected number (seconds) or ` +
+        `a string like "500ms" | "30s" | "3m" | "24h".`,
+      { code: 'duration_invalid' },
+    );
+  }
+  const value = Number(match[1]);
+  const unit = match[2] as 'ms' | 's' | 'm' | 'h';
+  return value * UNIT_MS[unit];
+}
+
+/** Parses a duration like {@link toMs} but returns whole seconds, rounding down. */
+export function toSeconds(input: Duration): number {
+  return Math.floor(toMs(input) / 1_000);
+}

package/src/utils/json.ts

@@ -0,0 +1,281 @@
+/**
+ * json.ts — key-order-insensitive comparison helpers for JSON-shaped values.
+ *
+ * Why this exists as a first-class, exported util:
+ *
+ * A `field.json()` value may be backed by a Postgres `jsonb` column, and **jsonb
+ * does not preserve object key order** (it reorders keys by length, then
+ * bytewise, and drops insignificant whitespace — see
+ * https://www.postgresql.org/docs/current/datatype-json.html). So a document an
+ * app wrote as `{type,text}` streams back in a delta as `{text,type}`: the same
+ * value, a different serialization.
+ *
+ * That bites any app that reconciles an Ablo row against an *external* state
+ * container it doesn't control — a rich-text editor (Tiptap/ProseMirror/Slate),
+ * a `useState`, a form buffer. The natural guard, `JSON.stringify(remote) ===
+ * JSON.stringify(local)`, is silently wrong because the two sides serialize keys
+ * in different orders, so it never matches — and the app re-applies the remote
+ * value on every render, clobbering in-flight edits and fighting the cursor.
+ *
+ * The fix is to compare order-insensitively. `deepEqual` does structural
+ * equality directly; `stableStringify` produces a canonical string (recursively
+ * sorted keys) for when you need a stable cache key / dependency value. The SDK
+ * already uses `deepEqual` internally for store-level echo detection; this
+ * module makes the same guarantee available to app authors so they don't each
+ * reinvent it.
+ *
+ * (If you need byte-exact key order preserved end-to-end, store the field in a
+ * `text` column instead of `jsonb` — Ablo's adaptive codec serializes verbatim
+ * there, matching Postgres's `json` type behavior.)
+ */
+
+import { AbloValidationError } from '../errors.js';
+import type { JsonValue } from '../types/streams.js';
+
+/**
+ * Takes an immutable, plain snapshot at a JSON persistence/wire boundary.
+ *
+ * Traversal intentionally creates fresh objects and arrays instead of relying
+ * on a framework-specific unwrapping API. That makes Proxy-wrapped plain data
+ * (including MobX observables) safe for IndexedDB's structured-clone algorithm
+ * while keeping the settlement core independent of any reactive framework.
+ *
+ * The accepted contract is deliberately narrower than `JSON.stringify`:
+ * values that JSON would silently corrupt (`NaN` to `null`, `Map` to `{}`) or
+ * cannot encode are rejected with a stable, path-aware validation error.
+ * Valid dates retain normal JSON semantics and become ISO strings. Undefined
+ * object properties are omitted for compatibility with optional object keys;
+ * root/array `undefined` and sparse arrays are rejected rather than becoming
+ * an ambiguous `null`.
+ */
+export function snapshotJsonValue(value: unknown, path = '$'): JsonValue {
+  try {
+    return snapshotJsonNode(value, path, new WeakMap<object, string>());
+  } catch (error) {
+    if (error instanceof AbloValidationError) throw error;
+    throw invalidJsonValue(path, 'could not be read safely', value, error);
+  }
+}
+
+function snapshotJsonNode(
+  value: unknown,
+  path: string,
+  active: WeakMap<object, string>,
+): JsonValue {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+    return value;
+  }
+
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw invalidJsonValue(path, 'must be a finite number', value);
+    }
+    return Object.is(value, -0) ? 0 : value;
+  }
+
+  if (value === undefined) {
+    throw invalidJsonValue(path, 'cannot be undefined here', value);
+  }
+  if (typeof value === 'bigint') {
+    throw invalidJsonValue(path, 'cannot be a bigint', value);
+  }
+  if (typeof value === 'function') {
+    throw invalidJsonValue(path, 'cannot be a function', value);
+  }
+  if (typeof value === 'symbol') {
+    throw invalidJsonValue(path, 'cannot be a symbol', value);
+  }
+
+  if (value instanceof Date) {
+    const timestamp = value.getTime();
+    if (!Number.isFinite(timestamp)) {
+      throw invalidJsonValue(path, 'cannot be an invalid Date', value);
+    }
+    return value.toISOString();
+  }
+
+  if (Array.isArray(value)) {
+    const firstPath = active.get(value);
+    if (firstPath !== undefined) {
+      throw invalidJsonValue(path, `forms a cycle back to ${firstPath}`, value);
+    }
+    active.set(value, path);
+    try {
+      const output: JsonValue[] = [];
+      for (let index = 0; index < value.length; index += 1) {
+        const itemPath = `${path}[${index}]`;
+        if (!(index in value)) {
+          throw invalidJsonValue(itemPath, 'cannot be a sparse array hole', undefined);
+        }
+        output.push(snapshotJsonNode(value[index], itemPath, active));
+      }
+      return Object.freeze(output);
+    } finally {
+      active.delete(value);
+    }
+  }
+
+  const object = value as object;
+  const firstPath = active.get(object);
+  if (firstPath !== undefined) {
+    throw invalidJsonValue(path, `forms a cycle back to ${firstPath}`, value);
+  }
+
+  let prototype: object | null;
+  try {
+    prototype = Object.getPrototypeOf(object) as object | null;
+  } catch (cause) {
+    throw invalidJsonValue(path, 'has an unreadable prototype', value, cause);
+  }
+  if (prototype !== null) {
+    const constructorDescriptor = Object.getOwnPropertyDescriptor(prototype, 'constructor');
+    const constructor = constructorDescriptor?.value;
+    if (typeof constructor !== 'function' || constructor.name !== 'Object') {
+      throw invalidJsonValue(path, 'must be a plain object', value);
+    }
+  }
+
+  active.set(object, path);
+  try {
+    let keys: (string | symbol)[];
+    try {
+      keys = Reflect.ownKeys(object);
+    } catch (cause) {
+      throw invalidJsonValue(path, 'has unreadable keys', value, cause);
+    }
+
+    for (const key of keys) {
+      if (typeof key !== 'symbol') continue;
+      let enumerable = false;
+      try {
+        enumerable = Object.getOwnPropertyDescriptor(object, key)?.enumerable === true;
+      } catch (cause) {
+        throw invalidJsonValue(path, 'has an unreadable symbol property', value, cause);
+      }
+      if (enumerable) {
+        throw invalidJsonValue(path, 'cannot contain enumerable symbol keys', value);
+      }
+    }
+
+    const output: Record<string, JsonValue> = {};
+    for (const key of keys) {
+      if (typeof key !== 'string') continue;
+      let descriptor: PropertyDescriptor | undefined;
+      try {
+        descriptor = Object.getOwnPropertyDescriptor(object, key);
+      } catch (cause) {
+        throw invalidJsonValue(jsonPath(path, key), 'has an unreadable property', value, cause);
+      }
+      if (!descriptor?.enumerable) continue;
+
+      let child: unknown;
+      try {
+        child = Reflect.get(object, key);
+      } catch (cause) {
+        throw invalidJsonValue(jsonPath(path, key), 'could not be read', value, cause);
+      }
+      // Matches JSON object semantics for optional fields without allowing
+      // undefined to become null inside arrays.
+      if (child === undefined) continue;
+
+      Object.defineProperty(output, key, {
+        configurable: true,
+        enumerable: true,
+        value: snapshotJsonNode(child, jsonPath(path, key), active),
+        writable: true,
+      });
+    }
+    return Object.freeze(output);
+  } finally {
+    active.delete(object);
+  }
+}
+
+function jsonPath(parent: string, key: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+    ? `${parent}.${key}`
+    : `${parent}[${JSON.stringify(key)}]`;
+}
+
+function invalidJsonValue(
+  path: string,
+  reason: string,
+  value: unknown,
+  cause?: unknown,
+): AbloValidationError {
+  const valueType = jsonValueType(value);
+  return new AbloValidationError(`Write payload ${path} ${reason}.`, {
+    code: 'write_payload_invalid',
+    param: path,
+    details: { path, reason, valueType },
+    ...(cause !== undefined ? { cause } : {}),
+  });
+}
+
+function jsonValueType(value: unknown): string {
+  if (value === null) return 'null';
+  try {
+    if (Array.isArray(value)) return 'array';
+    if (value instanceof Date) return 'Date';
+    if (typeof value === 'object') {
+      const name = Reflect.get(value, 'constructor')?.name;
+      return typeof name === 'string' ? name : 'object';
+    }
+  } catch {
+    return typeof value;
+  }
+  return typeof value;
+}
+
+/** Structural equality for JSON-shaped values (scalars, arrays, plain objects); key order is ignored. */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') {
+    return false;
+  }
+  const aArr = Array.isArray(a);
+  if (aArr !== Array.isArray(b)) return false;
+  if (aArr) {
+    const av = a as unknown[];
+    const bv = b as unknown[];
+    if (av.length !== bv.length) return false;
+    for (let i = 0; i < av.length; i++) {
+      if (!deepEqual(av[i], bv[i])) return false;
+    }
+    return true;
+  }
+  const ao = a as Record<string, unknown>;
+  const bo = b as Record<string, unknown>;
+  const ak = Object.keys(ao);
+  const bk = Object.keys(bo);
+  if (ak.length !== bk.length) return false;
+  for (const k of ak) {
+    if (!Object.prototype.hasOwnProperty.call(bo, k)) return false;
+    if (!deepEqual(ao[k], bo[k])) return false;
+  }
+  return true;
+}
+
+/**
+ * Canonical JSON serialization: recursively sorts object keys so two values that
+ * differ only in key order (e.g. a jsonb round-trip) produce the same string.
+ * Use this when you need a comparable/cacheable string rather than a boolean —
+ * e.g. an echo guard or a `useEffect`/`useMemo` dependency.
+ */
+export function stableStringify(value: unknown): string {
+  return JSON.stringify(sortKeysDeep(value));
+}
+
+function sortKeysDeep(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (value && typeof value === 'object') {
+    const source = value as Record<string, unknown>;
+    return Object.keys(source)
+      .sort()
+      .reduce<Record<string, unknown>>((acc, key) => {
+        acc[key] = sortKeysDeep(source[key]);
+        return acc;
+      }, {});
+  }
+  return value;
+}

package/src/webhooks/events.ts

@@ -0,0 +1,96 @@
+/**
+ * Translates a committed change from the transaction log into a typed webhook
+ * event your customers can consume. This module holds the event catalog and the
+ * delta-to-event mapping; it does not deliver, sign, retry, or verify events.
+ * Delivery and signing are handled by your webhook infrastructure, and the
+ * recipient verifies the signature with an off-the-shelf Standard Webhooks
+ * library.
+ *
+ * Every event carries a `syncId`, the position of the change in the transaction
+ * log, which increases monotonically. A recipient uses it two ways at once: to
+ * skip a change it has already processed, and to apply changes in the order they
+ * were committed.
+ */
+import type { SyncDeltaAction } from '@abloatai/transaction/wire/delta';
+
+/**
+ * Maps each delta action code to the verb that appears in an event type. Only
+ * the row-level create, update, delete, archive, and unarchive actions produce a
+ * webhook. The remaining action codes describe internal permission and
+ * visibility changes and are deliberately absent, so {@link deltaToWebhookEvent}
+ * returns `null` for them.
+ */
+const ACTION_VERB: Partial<Record<SyncDeltaAction, string>> = {
+  I: 'created',
+  U: 'updated',
+  D: 'deleted',
+  A: 'archived',
+  V: 'unarchived',
+};
+
+/**
+ * A webhook event delivered to a customer's endpoint, representing a single
+ * committed change to a row. {@link deltaToWebhookEvent} produces it, and the
+ * recipient verifies the delivery signature before trusting its contents.
+ */
+export interface AbloWebhookEvent {
+  /** A stable, unique event identifier equal to `String(syncId)`. Use it to
+   *  deduplicate deliveries. */
+  readonly id: string;
+  /** The event type, formatted as `<model>.<verb>`, such as `"report.updated"`.
+   *  Branch on this to route the event. */
+  readonly type: string;
+  /** The name of the model whose row changed, such as `"Report"`. */
+  readonly model: string;
+  /** The identifier of the row that changed. */
+  readonly objectId: string;
+  /** The change's position in the transaction log, increasing monotonically.
+   *  Order events by this value. */
+  readonly syncId: number;
+  /** The row as it stands after the change, or `null` when the change was a
+   *  delete. */
+  readonly data: Record<string, unknown> | null;
+  /** The time the change was committed, as an ISO 8601 timestamp. */
+  readonly createdAt: string;
+}
+
+/** The minimal delta shape {@link deltaToWebhookEvent} reads; a full server-side
+ *  delta record satisfies it. */
+export interface WebhookSourceDelta {
+  readonly id: number;
+  readonly actionType: string;
+  readonly modelName: string;
+  readonly modelId: string;
+  /** The row payload: an already-parsed object, a raw JSON string, or `null`. */
+  readonly data: Record<string, unknown> | string | null;
+  readonly createdAt: string;
+}
+
+function parseRow(data: WebhookSourceDelta['data']): Record<string, unknown> | null {
+  if (data == null) return null;
+  if (typeof data === 'string') {
+    return data === '' ? null : (JSON.parse(data) as Record<string, unknown>);
+  }
+  return data;
+}
+
+/**
+ * Converts a committed delta into an {@link AbloWebhookEvent}. Returns `null`
+ * when the delta records an internal permission or group change rather than a
+ * row-level change, in which case the caller emits no webhook. The mapping is
+ * deterministic: the event id and timestamp come directly from the delta.
+ */
+export function deltaToWebhookEvent(delta: WebhookSourceDelta): AbloWebhookEvent | null {
+  const verb = ACTION_VERB[delta.actionType as SyncDeltaAction];
+  if (!verb) return null; // an internal permission or group change, not a customer event
+
+  return {
+    id: String(delta.id),
+    type: `${delta.modelName.toLowerCase()}.${verb}`,
+    model: delta.modelName,
+    objectId: delta.modelId,
+    syncId: delta.id,
+    data: parseRow(delta.data),
+    createdAt: delta.createdAt,
+  };
+}

package/src/webhooks/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The public entry point for webhooks. Import {@link AbloWebhookEvent} to type
+ * your event handler, and use {@link deltaToWebhookEvent} to turn a committed
+ * change from the transaction log into an event to deliver. This module does not
+ * verify signatures and ships no cryptography; recipients verify deliveries with
+ * a standard webhooks library.
+ */
+export {
+  deltaToWebhookEvent,
+  type AbloWebhookEvent,
+  type WebhookSourceDelta,
+} from './events.js';