@abloatai/ablo 0.36.0 → 0.37.0

package/dist/transaction/utils/asyncIterator.js

@@ -1,135 +0,0 @@
-/**
- * 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(subscribe) {
-    const queue = [];
-    const resolvers = [];
-    let done = false;
-    const push = (value) => {
-        if (done)
-            return;
-        const resolver = resolvers.shift();
-        if (resolver) {
-            resolver({ value, done: false });
-        }
-        else {
-            queue.push(value);
-        }
-    };
-    const unsubscribe = subscribe(push);
-    const finish = () => {
-        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() {
-            if (done)
-                return { value: undefined, done: true };
-            if (queue.length > 0) {
-                return { value: queue.shift(), done: false };
-            }
-            return new Promise((resolve) => {
-                resolvers.push(resolve);
-            });
-        },
-        async return() {
-            return finish();
-        },
-        async throw(err) {
-            finish();
-            throw err;
-        },
-        [Symbol.asyncIterator]() {
-            return this;
-        },
-    };
-}
-export function asyncIteratorFrom(subscribe, getSnapshot) {
-    const queue = [];
-    // 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 = [];
-    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 = () => {
-        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() {
-            if (done)
-                return { value: undefined, done: true };
-            if (queue.length > 0) {
-                return { value: queue.shift(), done: false };
-            }
-            return new Promise((resolve) => {
-                resolvers.push(resolve);
-            });
-        },
-        async return() {
-            return finish();
-        },
-        async throw(err) {
-            finish();
-            throw err;
-        },
-        [Symbol.asyncIterator]() {
-            return this;
-        },
-    };
-}

package/dist/transaction/utils/duration.d.ts

@@ -1,50 +0,0 @@
-/**
- * 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';
-export type Duration = number | `${number}ms` | `${number}s` | `${number}m` | `${number}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 declare const durationSchema: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
-/**
- * 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 declare function toMs(input: Duration): number;
-/**
- * {@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 declare function parseDurationMs(input: string | number): number;
-/** Parses a duration like {@link toMs} but returns whole seconds, rounding down. */
-export declare function toSeconds(input: Duration): number;

package/dist/transaction/utils/duration.js

@@ -1,77 +0,0 @@
-/**
- * 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';
-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 = {
-    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) {
-    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) {
-    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];
-    return value * UNIT_MS[unit];
-}
-/** Parses a duration like {@link toMs} but returns whole seconds, rounding down. */
-export function toSeconds(input) {
-    return Math.floor(toMs(input) / 1_000);
-}

package/dist/transaction/utils/json.d.ts

@@ -1,57 +0,0 @@
-/**
- * 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 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 declare function snapshotJsonValue(value: unknown, path?: string): JsonValue;
-/** Structural equality for JSON-shaped values (scalars, arrays, plain objects); key order is ignored. */
-export declare function deepEqual(a: unknown, b: unknown): boolean;
-/**
- * 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 declare function stableStringify(value: unknown): string;

package/dist/transaction/utils/json.js

@@ -1,276 +0,0 @@
-/**
- * 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';
-/**
- * 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, path = '$') {
-    try {
-        return snapshotJsonNode(value, path, new WeakMap());
-    }
-    catch (error) {
-        if (error instanceof AbloValidationError)
-            throw error;
-        throw invalidJsonValue(path, 'could not be read safely', value, error);
-    }
-}
-function snapshotJsonNode(value, path, active) {
-    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 = [];
-            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;
-    const firstPath = active.get(object);
-    if (firstPath !== undefined) {
-        throw invalidJsonValue(path, `forms a cycle back to ${firstPath}`, value);
-    }
-    let prototype;
-    try {
-        prototype = Object.getPrototypeOf(object);
-    }
-    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;
-        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 = {};
-        for (const key of keys) {
-            if (typeof key !== 'string')
-                continue;
-            let descriptor;
-            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;
-            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, key) {
-    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
-        ? `${parent}.${key}`
-        : `${parent}[${JSON.stringify(key)}]`;
-}
-function invalidJsonValue(path, reason, value, cause) {
-    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) {
-    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, b) {
-    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;
-        const bv = b;
-        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;
-    const bo = b;
-    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) {
-    return JSON.stringify(sortKeysDeep(value));
-}
-function sortKeysDeep(value) {
-    if (Array.isArray(value))
-        return value.map(sortKeysDeep);
-    if (value && typeof value === 'object') {
-        const source = value;
-        return Object.keys(source)
-            .sort()
-            .reduce((acc, key) => {
-            acc[key] = sortKeysDeep(source[key]);
-            return acc;
-        }, {});
-    }
-    return value;
-}