meridian-sdk 1.2.1 → 1.3.0

package/dist/undo/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Undo/redo entry types for CRDT-aware per-client history.
+ *
+ * Each entry stores enough information to produce the inverse operation.
+ * RGA Delete is intentionally not recorded — tombstones are final and
+ * the content is not recoverable (same semantics as ProseMirror/Yjs).
+ */
+export interface RgaInsertEntry {
+    readonly kind: "rga_insert";
+    readonly crdtId: string;
+    /** HLC string "wall_ms:logical:node_id" of the inserted node. Undo = deleteById(nodeId). */
+    readonly nodeId: string;
+    /** Original visible position — used for redo re-insert. */
+    readonly pos: number;
+    /** The character that was inserted. */
+    readonly content: string;
+}
+export interface TreeAddEntry {
+    readonly kind: "tree_add";
+    readonly crdtId: string;
+    /** Node ID returned by addNode(). Undo = deleteNode(nodeId). */
+    readonly nodeId: string;
+    /** Stored for redo: re-add with same parent/position/value. */
+    readonly parentId: string | null;
+    readonly position: string;
+    readonly value: string;
+}
+export interface TreeDeleteEntry {
+    readonly kind: "tree_delete";
+    readonly crdtId: string;
+    readonly nodeId: string;
+    /** State captured before the delete — used to reconstruct addNode for undo. */
+    readonly parentId: string | null;
+    readonly position: string;
+    readonly value: string;
+    readonly updatedAt: string;
+}
+export interface TreeMoveEntry {
+    readonly kind: "tree_move";
+    readonly crdtId: string;
+    readonly nodeId: string;
+    readonly oldParentId: string | null;
+    readonly oldPosition: string;
+    /** Stored for redo. */
+    readonly newParentId: string | null;
+    readonly newPosition: string;
+}
+export interface TreeUpdateEntry {
+    readonly kind: "tree_update";
+    readonly crdtId: string;
+    readonly nodeId: string;
+    /** Captured before the update — used for undo. */
+    readonly previousValue: string;
+    readonly previousUpdatedAt: string;
+    /** Stored for redo. */
+    readonly newValue: string;
+}
+export type UndoEntry = RgaInsertEntry | TreeAddEntry | TreeDeleteEntry | TreeMoveEntry | TreeUpdateEntry;
+/** A batch groups one or more entries into a single logical undo step. */
+export interface UndoBatch {
+    readonly entries: readonly UndoEntry[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/undo/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/undo/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uBAAuB;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,uBAAuB;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,SAAS,GACjB,cAAc,GACd,YAAY,GACZ,eAAe,GACf,aAAa,GACb,eAAe,CAAC;AAEpB,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;CACxC"}

package/dist/undo/types.js

@@ -0,0 +1,9 @@
+/**
+ * Undo/redo entry types for CRDT-aware per-client history.
+ *
+ * Each entry stores enough information to produce the inverse operation.
+ * RGA Delete is intentionally not recorded — tombstones are final and
+ * the content is not recoverable (same semantics as ProseMirror/Yjs).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/undo/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/undo/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/utils/fractional.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Fractional indexing helpers for TreeCRDT sibling ordering.
+ *
+ * Positions are lexicographically ordered strings over the alphabet [a-z0-9].
+ * They can be compared with plain string comparison: "a0" < "b0" < "z9".
+ *
+ * Use these helpers to compute positions when inserting nodes between, before,
+ * or after existing siblings — without having to manage the alphabet manually.
+ *
+ * @example
+ * ```ts
+ * import { fi } from "meridian-sdk";
+ *
+ * const first = fi.start();            // "a0"
+ * const last  = fi.end();              // "z9"
+ * const mid   = fi.between("a0","z9"); // "m4" (midpoint)
+ * const prev  = fi.before("a0");       // "V9" (below a0)
+ * const next  = fi.after("z9");        // "{0" (above z9, still valid)
+ * ```
+ */
+/**
+ * Returns a position string strictly between `a` and `b`.
+ *
+ * Both `a` and `b` must be valid fractional index strings, and `a < b`
+ * lexicographically. Uses BigInt arithmetic to find the exact midpoint,
+ * appending an extra character when the gap is too small.
+ *
+ * @param a - Lower bound (exclusive).
+ * @param b - Upper bound (exclusive).
+ */
+export declare function between(a: string, b: string): string;
+/**
+ * Returns a position string that sorts before `a`.
+ *
+ * @param a - The reference position.
+ */
+export declare function before(a: string): string;
+/**
+ * Returns a position string that sorts after `b`.
+ *
+ * @param b - The reference position.
+ */
+export declare function after(b: string): string;
+/**
+ * Returns the canonical start position — the lowest recommended initial value.
+ */
+export declare function start(): string;
+/**
+ * Returns the canonical end position — the highest recommended initial value.
+ */
+export declare function end(): string;
+/**
+ * Computes an array of `n` evenly-spaced positions between `a` and `b`
+ * (exclusive). Useful for bulk-inserting nodes in order.
+ *
+ * @param a - Lower bound (exclusive).
+ * @param b - Upper bound (exclusive).
+ * @param n - Number of positions to generate.
+ */
+export declare function spread(a: string, b: string, n: number): string[];
+/**
+ * Namespace object for convenient import.
+ *
+ * @example
+ * ```ts
+ * import { fi } from "meridian-sdk";
+ * const pos = fi.between("a0", "z9");
+ * ```
+ */
+export declare const fi: {
+    between: typeof between;
+    before: typeof before;
+    after: typeof after;
+    start: typeof start;
+    end: typeof end;
+    spread: typeof spread;
+};
+//# sourceMappingURL=fractional.d.ts.map

package/dist/utils/fractional.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fractional.d.ts","sourceRoot":"","sources":["../../src/utils/fractional.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA+CH;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAgBpD;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvC;AAED;;GAEG;AACH,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED;;GAEG;AACH,wBAAgB,GAAG,IAAI,MAAM,CAE5B;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAoBhE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,EAAE;;;;;;;CAAiD,CAAC"}

package/dist/utils/fractional.js

@@ -0,0 +1,159 @@
+/**
+ * Fractional indexing helpers for TreeCRDT sibling ordering.
+ *
+ * Positions are lexicographically ordered strings over the alphabet [a-z0-9].
+ * They can be compared with plain string comparison: "a0" < "b0" < "z9".
+ *
+ * Use these helpers to compute positions when inserting nodes between, before,
+ * or after existing siblings — without having to manage the alphabet manually.
+ *
+ * @example
+ * ```ts
+ * import { fi } from "meridian-sdk";
+ *
+ * const first = fi.start();            // "a0"
+ * const last  = fi.end();              // "z9"
+ * const mid   = fi.between("a0","z9"); // "m4" (midpoint)
+ * const prev  = fi.before("a0");       // "V9" (below a0)
+ * const next  = fi.after("z9");        // "{0" (above z9, still valid)
+ * ```
+ */
+/** Characters used in fractional index strings, in ascending order. */
+const CHARS = "0123456789abcdefghijklmnopqrstuvwxyz";
+const BASE = BigInt(CHARS.length); // 36
+/** Encode a position string to a BigInt for arithmetic. */
+function toNum(s) {
+    let n = 0n;
+    for (const c of s) {
+        const idx = CHARS.indexOf(c);
+        if (idx === -1)
+            throw new Error(`Invalid fractional index character: "${c}"`);
+        n = n * BASE + BigInt(idx);
+    }
+    return n;
+}
+/** Decode a BigInt back to a fixed-length position string. */
+function toStr(n, len) {
+    let s = "";
+    for (let i = 0; i < len; i++) {
+        s = (CHARS[Number(n % BASE)] ?? "0") + s;
+        n = n / BASE;
+    }
+    return s;
+}
+/** Increment a position string by 1 in base-36. */
+function increment(s) {
+    const n = toNum(s) + 1n;
+    // If the result requires more digits, extend by one char
+    const maxForLen = BASE ** BigInt(s.length) - 1n;
+    if (n > maxForLen)
+        return toStr(n, s.length + 1);
+    return toStr(n, s.length);
+}
+/** Decrement a position string by 1 in base-36, trimming trailing zeros. */
+function decrement(s) {
+    const n = toNum(s) - 1n;
+    let result = toStr(n < 0n ? 0n : n, s.length);
+    // Trim trailing zeros beyond length 1
+    while (result.length > 1 && result.endsWith("0"))
+        result = result.slice(0, -1);
+    // If underflow, prepend a zero digit
+    if (n < 0n)
+        return "0" + result;
+    return result;
+}
+/**
+ * Returns a position string strictly between `a` and `b`.
+ *
+ * Both `a` and `b` must be valid fractional index strings, and `a < b`
+ * lexicographically. Uses BigInt arithmetic to find the exact midpoint,
+ * appending an extra character when the gap is too small.
+ *
+ * @param a - Lower bound (exclusive).
+ * @param b - Upper bound (exclusive).
+ */
+export function between(a, b) {
+    if (a >= b)
+        throw new Error(`between: a must be < b (got "${a}" >= "${b}")`);
+    // Pad both to the same length + 1 extra digit for precision
+    const len = Math.max(a.length, b.length) + 1;
+    const aPadded = a.padEnd(len, "0");
+    const bPadded = b.padEnd(len, "0");
+    const an = toNum(aPadded);
+    const bn = toNum(bPadded);
+    const mid = (an + bn) / 2n;
+    let result = toStr(mid, len);
+    // Trim trailing zeros for cleaner output (keep min length 1)
+    while (result.length > 1 && result.endsWith("0"))
+        result = result.slice(0, -1);
+    return result;
+}
+/**
+ * Returns a position string that sorts before `a`.
+ *
+ * @param a - The reference position.
+ */
+export function before(a) {
+    return decrement(a);
+}
+/**
+ * Returns a position string that sorts after `b`.
+ *
+ * @param b - The reference position.
+ */
+export function after(b) {
+    return increment(b);
+}
+/**
+ * Returns the canonical start position — the lowest recommended initial value.
+ */
+export function start() {
+    return "a0";
+}
+/**
+ * Returns the canonical end position — the highest recommended initial value.
+ */
+export function end() {
+    return "z9";
+}
+/**
+ * Computes an array of `n` evenly-spaced positions between `a` and `b`
+ * (exclusive). Useful for bulk-inserting nodes in order.
+ *
+ * @param a - Lower bound (exclusive).
+ * @param b - Upper bound (exclusive).
+ * @param n - Number of positions to generate.
+ */
+export function spread(a, b, n) {
+    if (n <= 0)
+        return [];
+    if (n === 1)
+        return [between(a, b)];
+    const positions = [];
+    let lo = a;
+    for (let i = 0; i < n; i++) {
+        // Divide the remaining range into (n - i) equal slots
+        const remaining = n - i;
+        // Approximate: compute a position 1/(remaining+1) through [lo, b]
+        // We do this iteratively by bisecting
+        let hi = b;
+        for (let step = 0; step < Math.ceil(Math.log2(remaining + 1)); step++) {
+            hi = between(lo, b);
+        }
+        const pos = between(lo, b);
+        positions.push(pos);
+        lo = pos;
+    }
+    return positions;
+}
+/**
+ * Namespace object for convenient import.
+ *
+ * @example
+ * ```ts
+ * import { fi } from "meridian-sdk";
+ * const pos = fi.between("a0", "z9");
+ * ```
+ */
+export const fi = { between, before, after, start, end, spread };
+//# sourceMappingURL=fractional.js.map

package/dist/utils/fractional.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fractional.js","sourceRoot":"","sources":["../../src/utils/fractional.ts"],"names":[],"mappings":"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"}

package/dist/validation/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Runtime validation for CRDT string values.
+ *
+ * Values stored in TreeCRDT and RGA are always strings on the wire. This
+ * layer lets you attach a validator to a handle so that ops are checked
+ * before being sent. Invalid values throw a `CrdtValidationError`.
+ *
+ * The validator interface is intentionally minimal — plug in Zod, Valibot,
+ * ArkType, or a plain function without any SDK dependency on those libraries.
+ *
+ * @example Using Zod:
+ * ```ts
+ * import { z } from "zod";
+ * import { zodValidator } from "meridian-sdk";
+ *
+ * const schema = z.object({ title: z.string(), done: z.boolean() });
+ * const tree = client.tree("tasks", { validator: zodValidator(schema) });
+ *
+ * // Validated — value is parsed JSON then checked against schema
+ * tree.addNode(null, "a0", JSON.stringify({ title: "Task 1", done: false }));
+ *
+ * // Throws CrdtValidationError
+ * tree.addNode(null, "a0", JSON.stringify({ title: 42 }));
+ * ```
+ *
+ * @example Using a plain function:
+ * ```ts
+ * import { fnValidator } from "meridian-sdk";
+ *
+ * const tree = client.tree("tasks", {
+ *   validator: fnValidator((v) => typeof v === "string" && v.length > 0),
+ * });
+ * ```
+ */
+/** Thrown when a CRDT value fails validation before being sent. */
+export declare class CrdtValidationError extends Error {
+    /** The raw string value that failed. */
+    readonly value: string;
+    /** Human-readable reason from the validator. */
+    readonly reason: string;
+    readonly name = "CrdtValidationError";
+    constructor(
+    /** The raw string value that failed. */
+    value: string, 
+    /** Human-readable reason from the validator. */
+    reason: string);
+}
+/**
+ * A validator that can be attached to a CRDT handle.
+ *
+ * `validate` receives the raw string value as stored on the wire. It should
+ * throw or return `{ ok: false, error: string }` for invalid values, and
+ * return `{ ok: true }` or `undefined` for valid ones.
+ */
+export interface CrdtValidator {
+    /**
+     * Validate `value`. Throw, or return `{ ok: false, error }` to reject.
+     * Return `{ ok: true }` or `undefined` to accept.
+     */
+    validate(value: string): {
+        ok: false;
+        error: string;
+    } | {
+        ok: true;
+    } | undefined | void;
+}
+/**
+ * Run a validator against a value. Throws `CrdtValidationError` on failure.
+ * No-ops if `validator` is undefined.
+ */
+export declare function runValidator(validator: CrdtValidator | undefined, value: string): void;
+/**
+ * Creates a `CrdtValidator` from any Zod schema (or any object with a
+ * `safeParse` method returning `{ success, error }`).
+ *
+ * The string value is JSON-parsed before being passed to the schema.
+ * If JSON parsing fails, the raw string is passed as-is.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * const validator = zodValidator(z.object({ title: z.string() }));
+ * ```
+ */
+export declare function zodValidator(schema: {
+    safeParse(value: unknown): {
+        success: true;
+    } | {
+        success: false;
+        error: {
+            message: string;
+        };
+    };
+}): CrdtValidator;
+/**
+ * Creates a `CrdtValidator` from a plain predicate function.
+ *
+ * The function receives the raw string value. Return `true` to accept,
+ * `false` or a string (used as the error message) to reject.
+ *
+ * @example
+ * ```ts
+ * const validator = fnValidator((v) => v.length > 0 || "Value must not be empty");
+ * ```
+ */
+export declare function fnValidator(fn: (value: string) => boolean | string): CrdtValidator;
+//# sourceMappingURL=index.d.ts.map

package/dist/validation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,mEAAmE;AACnE,qBAAa,mBAAoB,SAAQ,KAAK;IAG1C,wCAAwC;aACxB,KAAK,EAAE,MAAM;IAC7B,gDAAgD;aAChC,MAAM,EAAE,MAAM;IALhC,SAAkB,IAAI,yBAAyB;;IAE7C,wCAAwC;IACxB,KAAK,EAAE,MAAM;IAC7B,gDAAgD;IAChC,MAAM,EAAE,MAAM;CAIjC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG,SAAS,GAAG,IAAI,CAAC;CACzF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,aAAa,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAYtF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE;IACnC,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG;QAAE,OAAO,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CAC/F,GAAG,aAAa,CAgBhB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,MAAM,GACtC,aAAa,CASf"}

package/dist/validation/index.js

@@ -0,0 +1,123 @@
+/**
+ * Runtime validation for CRDT string values.
+ *
+ * Values stored in TreeCRDT and RGA are always strings on the wire. This
+ * layer lets you attach a validator to a handle so that ops are checked
+ * before being sent. Invalid values throw a `CrdtValidationError`.
+ *
+ * The validator interface is intentionally minimal — plug in Zod, Valibot,
+ * ArkType, or a plain function without any SDK dependency on those libraries.
+ *
+ * @example Using Zod:
+ * ```ts
+ * import { z } from "zod";
+ * import { zodValidator } from "meridian-sdk";
+ *
+ * const schema = z.object({ title: z.string(), done: z.boolean() });
+ * const tree = client.tree("tasks", { validator: zodValidator(schema) });
+ *
+ * // Validated — value is parsed JSON then checked against schema
+ * tree.addNode(null, "a0", JSON.stringify({ title: "Task 1", done: false }));
+ *
+ * // Throws CrdtValidationError
+ * tree.addNode(null, "a0", JSON.stringify({ title: 42 }));
+ * ```
+ *
+ * @example Using a plain function:
+ * ```ts
+ * import { fnValidator } from "meridian-sdk";
+ *
+ * const tree = client.tree("tasks", {
+ *   validator: fnValidator((v) => typeof v === "string" && v.length > 0),
+ * });
+ * ```
+ */
+/** Thrown when a CRDT value fails validation before being sent. */
+export class CrdtValidationError extends Error {
+    value;
+    reason;
+    name = "CrdtValidationError";
+    constructor(
+    /** The raw string value that failed. */
+    value, 
+    /** Human-readable reason from the validator. */
+    reason) {
+        super(`CrdtValidationError: ${reason} (value: ${JSON.stringify(value)})`);
+        this.value = value;
+        this.reason = reason;
+    }
+}
+/**
+ * Run a validator against a value. Throws `CrdtValidationError` on failure.
+ * No-ops if `validator` is undefined.
+ */
+export function runValidator(validator, value) {
+    if (validator === undefined)
+        return;
+    let result;
+    try {
+        result = validator.validate(value);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new CrdtValidationError(value, reason);
+    }
+    if (result !== undefined && result !== null && !result.ok) {
+        throw new CrdtValidationError(value, result.error);
+    }
+}
+/**
+ * Creates a `CrdtValidator` from any Zod schema (or any object with a
+ * `safeParse` method returning `{ success, error }`).
+ *
+ * The string value is JSON-parsed before being passed to the schema.
+ * If JSON parsing fails, the raw string is passed as-is.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * const validator = zodValidator(z.object({ title: z.string() }));
+ * ```
+ */
+export function zodValidator(schema) {
+    return {
+        validate(raw) {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                parsed = raw;
+            }
+            const result = schema.safeParse(parsed);
+            if (!result.success) {
+                return { ok: false, error: result.error.message };
+            }
+            return { ok: true };
+        },
+    };
+}
+/**
+ * Creates a `CrdtValidator` from a plain predicate function.
+ *
+ * The function receives the raw string value. Return `true` to accept,
+ * `false` or a string (used as the error message) to reject.
+ *
+ * @example
+ * ```ts
+ * const validator = fnValidator((v) => v.length > 0 || "Value must not be empty");
+ * ```
+ */
+export function fnValidator(fn) {
+    return {
+        validate(raw) {
+            const result = fn(raw);
+            if (result === true)
+                return { ok: true };
+            if (result === false)
+                return { ok: false, error: "Validation failed" };
+            return { ok: false, error: result };
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/validation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,mEAAmE;AACnE,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAI1B;IAEA;IALA,IAAI,GAAG,qBAAqB,CAAC;IAC/C;IACE,wCAAwC;IACxB,KAAa;IAC7B,gDAAgD;IAChC,MAAc;QAE9B,KAAK,CAAC,wBAAwB,MAAM,YAAY,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAJ1D,UAAK,GAAL,KAAK,CAAQ;QAEb,WAAM,GAAN,MAAM,CAAQ;IAGhC,CAAC;CACF;AAiBD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,SAAoC,EAAE,KAAa;IAC9E,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO;IACpC,IAAI,MAA6C,CAAC;IAClD,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChE,MAAM,IAAI,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QAC1D,MAAM,IAAI,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IACrD,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,MAE5B;IACC,OAAO;QACL,QAAQ,CAAC,GAAW;YAClB,IAAI,MAAe,CAAC;YACpB,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,GAAG,GAAG,CAAC;YACf,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YACxC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;YACpD,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CACzB,EAAuC;IAEvC,OAAO;QACL,QAAQ,CAAC,GAAW;YAClB,MAAM,MAAM,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;YACvB,IAAI,MAAM,KAAK,IAAI;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;YACzC,IAAI,MAAM,KAAK,KAAK;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC;YACvE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QACtC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meridian-sdk",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "TypeScript SDK for Meridian CRDT server",
   "type": "module",
   "main": "./dist/index.js",