state-sync-log 0.9.0 → 0.10.0

package/dist/types/createOps/constant.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Constants for createOps.
+ * Simplified from original source - removed dataTypes (mark feature).
+ */
+export declare const PROXY_DRAFT: unique symbol;
+export declare const iteratorSymbol: typeof Symbol.iterator;

package/dist/types/createOps/createOps.d.ts

@@ -0,0 +1,25 @@
+import { CreateOpsResult, Draft } from './interface';
+/**
+ * Create operations from mutable-style mutations.
+ *
+ * @param base - The base state (will not be mutated)
+ * @param mutate - A function that mutates the draft
+ * @returns An object containing the next state and the operations performed
+ *
+ * @example
+ * ```ts
+ * const state = { list: [{ text: 'Learn', done: false }] };
+ *
+ * const { nextState, ops } = createOps(state, (draft) => {
+ *   draft.list[0].done = true;
+ *   draft.list.push({ text: 'Practice', done: false });
+ * });
+ *
+ * // ops contains the operations that were performed:
+ * // [
+ * //   { kind: 'set', path: ['list', 0], key: 'done', value: true },
+ * //   { kind: 'splice', path: ['list'], index: 1, deleteCount: 0, inserts: [{ text: 'Practice', done: false }] }
+ * // ]
+ * ```
+ */
+export declare function createOps<T extends object>(base: T, mutate: (draft: Draft<T>) => void): CreateOpsResult<T>;

package/dist/types/createOps/current.d.ts

@@ -0,0 +1,13 @@
+import { Draft } from './interface';
+/**
+ * `current(draft)` to get current state in the draft mutation function.
+ *
+ * @example
+ * ```ts
+ * const { nextState, ops } = createOps(baseState, (draft) => {
+ *   draft.foo.bar = 'new value';
+ *   console.log(current(draft.foo)); // { bar: 'new value' }
+ * });
+ * ```
+ */
+export declare function current<T extends object>(target: Draft<T>): T;

package/dist/types/createOps/draft.d.ts

@@ -0,0 +1,14 @@
+import { Finalities, Op, ProxyDraft } from './interface';
+/**
+ * Create a draft proxy for a value
+ */
+export declare function createDraft<T extends object>(options: {
+    original: T;
+    parentDraft?: ProxyDraft | null;
+    key?: string | number;
+    finalities: Finalities;
+}): T;
+/**
+ * Finalize a draft and return the result with ops
+ */
+export declare function finalizeDraft<T>(result: T, returnedValue: [T] | []): [T, Op[]];

package/dist/types/createOps/draftify.d.ts

@@ -0,0 +1,5 @@
+import { Op } from './interface';
+/**
+ * Create a draft and return a finalize function
+ */
+export declare function draftify<T extends object>(baseState: T): [T, (returnedValue: [T] | []) => [T, Op[]]];

package/dist/types/createOps/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * createOps - Proxy-based mutable-style API for generating operations.
+ *
+ * Forked from mutative (https://github.com/unadlib/mutative)
+ * MIT License
+ */
+export { createOps } from './createOps';
+export { current } from './current';
+export type { CreateOpsResult, Draft, Immutable, Op, Path } from './interface';
+export { original } from './original';
+export { addToSet, deleteFromSet } from './setHelpers';
+export { isDraft, isDraftable } from './utils';

package/dist/types/createOps/interface.d.ts

@@ -0,0 +1,74 @@
+import { JSONPrimitive, JSONValue, Path } from '../json';
+import { Op } from '../operations';
+export type { Op, Path, JSONValue };
+export declare enum DraftType {
+    Object = 0,
+    Array = 1
+}
+/**
+ * Finalities - shared state for the draft tree
+ */
+export interface Finalities {
+    /** Finalization callbacks (for unwrapping child drafts) */
+    draft: (() => void)[];
+    /** Revoke functions for all proxies */
+    revoke: (() => void)[];
+    /** Set of handled objects (for cycle detection) */
+    handledSet: WeakSet<object>;
+    /** Cache of created drafts */
+    draftsCache: WeakSet<object>;
+    /** List of operations performed in this draft session (eager logging) */
+    ops: Op[];
+    /** Root draft of the tree (set when creating the root draft) */
+    rootDraft: ProxyDraft | null;
+}
+/**
+ * Internal proxy draft state
+ */
+export interface ProxyDraft<T = any> {
+    /** Type of the draft (Object or Array) */
+    type: DraftType;
+    /** Whether this draft has been mutated */
+    operated?: boolean;
+    /** Whether finalization has been completed */
+    finalized: boolean;
+    /** The original (unmodified) value */
+    original: T;
+    /** The shallow copy (created on first mutation) */
+    copy: T | null;
+    /** The proxy instance */
+    proxy: T | null;
+    /** Finalities container (shared across draft tree) */
+    finalities: Finalities;
+    /** Parent draft (for path tracking) */
+    parent?: ProxyDraft | null;
+    /** Key in parent */
+    key?: string | number;
+    /** Track which keys have been assigned (key -> true=assigned, false=deleted) */
+    assignedMap?: Map<PropertyKey, boolean>;
+    /** Count of positions this draft exists at (for aliasing optimization) */
+    aliasCount: number;
+}
+/**
+ * Result of createOps
+ */
+export interface CreateOpsResult<T> {
+    /** The new immutable state */
+    nextState: T;
+    /** The operations that were performed */
+    ops: Op[];
+}
+/** Primitive types that don't need drafting */
+type Primitive = JSONPrimitive;
+/**
+ * Draft type - makes all properties mutable for editing
+ */
+export type Draft<T> = T extends Primitive ? T : T extends object ? {
+    -readonly [K in keyof T]: Draft<T[K]>;
+} : T;
+/**
+ * Immutable type - makes all properties readonly
+ */
+export type Immutable<T> = T extends Primitive ? T : T extends object ? {
+    readonly [K in keyof T]: Immutable<T[K]>;
+} : T;

package/dist/types/createOps/original.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Get the original value from a draft.
+ */
+/**
+ * `original(draft)` to get original state in the draft mutation function.
+ *
+ * @example
+ * ```ts
+ * const { nextState, ops } = createOps(baseState, (draft) => {
+ *   draft.foo.bar = 'new value';
+ *   console.log(original(draft.foo)); // { bar: 'old value' }
+ * });
+ * ```
+ */
+export declare function original<T>(target: T): T;

package/dist/types/createOps/pushOp.d.ts

@@ -0,0 +1,9 @@
+import { Op, ProxyDraft } from './interface';
+/**
+ * Push an operation to the ops log.
+ * Values should already be cloned by the caller to avoid aliasing issues.
+ *
+ * When the target draft exists at multiple positions (due to aliasing),
+ * this function emits ops for all positions to maintain consistency.
+ */
+export declare function pushOp(proxyDraft: ProxyDraft, op: Op): void;

package/dist/types/createOps/setHelpers.d.ts

@@ -0,0 +1,25 @@
+import { JSONValue } from '../json';
+/**
+ * Add a value to an array if it doesn't already exist (set semantics).
+ * Generates an `addToSet` operation.
+ *
+ * @example
+ * ```ts
+ * createOps(state, (draft) => {
+ *   addToSet(draft.tags, 'newTag'); // Only adds if not present
+ * });
+ * ```
+ */
+export declare function addToSet<T extends JSONValue>(draft: T[], value: T): void;
+/**
+ * Remove a value from an array (set semantics).
+ * Generates a `deleteFromSet` operation.
+ *
+ * @example
+ * ```ts
+ * createOps(state, (draft) => {
+ *   deleteFromSet(draft.tags, 'oldTag'); // Removes all matching items
+ * });
+ * ```
+ */
+export declare function deleteFromSet<T extends JSONValue>(draft: T[], value: T): void;

package/dist/types/createOps/utils.d.ts

@@ -0,0 +1,95 @@
+import { DraftType, ProxyDraft } from './interface';
+/**
+ * Get the latest value (copy if exists, otherwise original)
+ */
+export declare function latest<T>(proxyDraft: ProxyDraft<T>): T;
+/**
+ * Check if the value is a draft
+ */
+export declare function isDraft(target: unknown): boolean;
+/**
+ * Get the ProxyDraft from a draft value
+ */
+export declare function getProxyDraft<T>(value: unknown): ProxyDraft<T> | null;
+/**
+ * Get the actual value from a draft (copy or original)
+ */
+export declare function getValue<T extends object>(value: T): T;
+/**
+ * Check if a value is draftable (plain object or array)
+ * We only support plain objects and arrays - no Map, Set, Date, etc.
+ */
+export declare function isDraftable(value: unknown): value is object;
+/**
+ * Get the draft type
+ */
+export declare function getType(target: unknown): DraftType;
+/**
+ * Get a value by key
+ */
+export declare function get(target: object, key: PropertyKey): unknown;
+/**
+ * Set a value by key
+ */
+export declare function set(target: object, key: PropertyKey, value: unknown): void;
+/**
+ * Check if a key exists (own property)
+ */
+export declare function has(target: object, key: PropertyKey): boolean;
+/**
+ * Peek at a value (through drafts)
+ */
+export declare function peek(target: object, key: PropertyKey): unknown;
+/**
+ * SameValue comparison (handles -0 and NaN)
+ */
+export declare function isEqual(x: unknown, y: unknown): boolean;
+/**
+ * Revoke all proxies in a draft tree
+ */
+export declare function revokeProxy(proxyDraft: ProxyDraft | null): void;
+/**
+ * Get the path from root to this draft
+ */
+export declare function getPath(target: ProxyDraft, path?: (string | number)[]): (string | number)[] | null;
+/**
+ * Get the path from root to this draft, or throw if not available
+ */
+export declare function getPathOrThrow(target: ProxyDraft): (string | number)[];
+/**
+ * Find all paths to a given draft by searching the tree.
+ * This handles aliasing where the same draft exists at multiple positions.
+ */
+export declare function getAllPathsForDraft(rootDraft: ProxyDraft, targetDraft: ProxyDraft): (string | number)[][];
+/**
+ * Get a property descriptor from the prototype chain
+ */
+export declare function getDescriptor(target: object, key: PropertyKey): PropertyDescriptor | undefined;
+/**
+ * Create a shallow copy of an object or array
+ */
+export declare function shallowCopy<T>(original: T): T;
+/**
+ * Ensure a draft has a shallow copy
+ */
+export declare function ensureShallowCopy(target: ProxyDraft): void;
+/**
+ * Deep clone a value, unwrapping any drafts
+ */
+export declare function deepClone<T>(target: T): T;
+/**
+ * Clone if the value is a draft, otherwise return as-is
+ */
+export declare function cloneIfNeeded<T>(target: T): T;
+/**
+ * Mark a draft as changed (operated)
+ */
+export declare function markChanged(target: ProxyDraft): void;
+/**
+ * Iterate over object/array entries
+ */
+export declare function forEach<T extends object>(target: T, callback: (key: PropertyKey, value: unknown, target: T) => void): void;
+/**
+ * Handle nested values during finalization
+ */
+export declare function handleValue(target: unknown, handledSet: WeakSet<object>): void;

package/dist/types/draft.d.ts

@@ -32,11 +32,11 @@ export declare function isDraftModified<T extends JSONObject>(ctx: DraftContext<
 /**
  * Applies a single "set" operation to the draft with copy-on-write.
  */
-export declare function draftSet<T extends JSONObject>(ctx: DraftContext<T>, path: Path, key: string, value: JSONValue): void;
+export declare function draftSet<T extends JSONObject>(ctx: DraftContext<T>, path: Path, key: string | number, value: JSONValue): void;
 /**
  * Applies a single "delete" operation to the draft with copy-on-write.
  */
-export declare function draftDelete<T extends JSONObject>(ctx: DraftContext<T>, path: Path, key: string): void;
+export declare function draftDelete<T extends JSONObject>(ctx: DraftContext<T>, path: Path, key: string | number): void;
 /**
  * Applies a single "splice" operation to the draft with copy-on-write.
  */

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 export type { CheckpointKey, CheckpointRecord } from './checkpoints';
+export * from './createOps';
 export { createStateSyncLog, type StateSyncLogController, type StateSyncLogOptions, } from './createStateSyncLog';
 export type { JSONObject, JSONValue, Path } from './json';
 export { type ApplyOpsOptions, applyOps, type Op, type ValidateFn } from './operations';

package/dist/types/json.d.ts

@@ -6,7 +6,7 @@ export type Path = readonly (string | number)[];
 /**
  * A JSON primitive.
  */
-export type JSONPrimitive = null | boolean | number | string;
+export type JSONPrimitive = undefined | null | boolean | number | string;
 /**
  * A JSON record.
  */

package/dist/types/operations.d.ts

@@ -6,12 +6,12 @@ import { JSONObject, JSONValue, Path } from './json';
 export type Op = {
     kind: "set";
     path: Path;
-    key: string;
+    key: string | number;
     value: JSONValue;
 } | {
     kind: "delete";
     path: Path;
-    key: string;
+    key: string | number;
 } | {
     kind: "splice";
     path: Path;

package/dist/types/utils.d.ts

@@ -21,3 +21,8 @@ export declare function deepClone<T>(value: T): T;
  * Creates a lazy memoized getter.
  */
 export declare function lazy<T>(fn: () => T): () => T;
+/**
+ * Checks if a string is a valid non-negative integer array index.
+ * Returns the numeric value if valid, or null if invalid.
+ */
+export declare function parseArrayIndex(key: string): number | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-sync-log",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Validated Replicated State Machine built on Yjs. Combine CRDT offline capabilities with strict business logic validation, state reconciliation, and audit trails.",
   "keywords": [
     "state-sync",

package/src/createOps/constant.ts

@@ -0,0 +1,10 @@
+/**
+ * Constants for createOps.
+ * Simplified from original source - removed dataTypes (mark feature).
+ */
+
+// Symbol to identify proxy drafts - accessible for 3rd party
+export const PROXY_DRAFT = Symbol.for("__CREATEOPS_PROXY_DRAFT__")
+
+// Symbol iterator
+export const iteratorSymbol: typeof Symbol.iterator = Symbol.iterator

package/src/createOps/createOps.ts

@@ -0,0 +1,97 @@
+/**
+ * createOps - Main API for generating operations from mutable-style mutations.
+ *
+ * Forked from mutative (https://github.com/unadlib/mutative)
+ * MIT License
+ */
+
+import { current } from "./current"
+import { draftify } from "./draftify"
+import type { CreateOpsResult, Draft } from "./interface"
+import { getProxyDraft, isDraft, isDraftable, isEqual, revokeProxy } from "./utils"
+
+/**
+ * Create operations from mutable-style mutations.
+ *
+ * @param base - The base state (will not be mutated)
+ * @param mutate - A function that mutates the draft
+ * @returns An object containing the next state and the operations performed
+ *
+ * @example
+ * ```ts
+ * const state = { list: [{ text: 'Learn', done: false }] };
+ *
+ * const { nextState, ops } = createOps(state, (draft) => {
+ *   draft.list[0].done = true;
+ *   draft.list.push({ text: 'Practice', done: false });
+ * });
+ *
+ * // ops contains the operations that were performed:
+ * // [
+ * //   { kind: 'set', path: ['list', 0], key: 'done', value: true },
+ * //   { kind: 'splice', path: ['list'], index: 1, deleteCount: 0, inserts: [{ text: 'Practice', done: false }] }
+ * // ]
+ * ```
+ */
+export function createOps<T extends object>(
+  base: T,
+  mutate: (draft: Draft<T>) => void
+): CreateOpsResult<T> {
+  // Handle case where base is already a draft
+  const state = isDraft(base) ? current(base as Draft<T>) : base
+
+  // Validate that state is draftable
+  if (!isDraftable(state)) {
+    throw new Error(`createOps() only supports plain objects and arrays.`)
+  }
+
+  // Create draft
+  const [draft, finalize] = draftify(state)
+
+  // Run mutation
+  let result: unknown
+  try {
+    result = mutate(draft as Draft<T>)
+  } catch (error) {
+    revokeProxy(getProxyDraft(draft))
+    throw error
+  }
+
+  // Handle return value
+  const proxyDraft = getProxyDraft(draft)!
+
+  // Check for invalid return values
+  if (result !== undefined && !isDraft(result)) {
+    if (!isEqual(result, draft) && proxyDraft.operated) {
+      throw new Error(
+        `Either the value is returned as a new non-draft value, or only the draft is modified without returning any value.`
+      )
+    }
+    // User returned a new value - use it as the next state
+    // Note: We don't support rawReturn, so returning a non-draft value replaces the state
+    // but we can't generate meaningful ops for this case
+    if (result !== undefined) {
+      const [, ops] = finalize([])
+      return { nextState: result as T, ops }
+    }
+  }
+
+  // Standard flow - finalize the draft
+  if (result === draft || result === undefined) {
+    const [nextState, ops] = finalize([])
+    return { nextState, ops }
+  }
+
+  // Returned a different draft (child)
+  const returnedProxyDraft = getProxyDraft(result)
+  if (returnedProxyDraft) {
+    if (returnedProxyDraft.operated) {
+      throw new Error(`Cannot return a modified child draft.`)
+    }
+    const [, ops] = finalize([])
+    return { nextState: current(result as object) as T, ops }
+  }
+
+  const [nextState, ops] = finalize([])
+  return { nextState, ops }
+}

package/src/createOps/current.ts

@@ -0,0 +1,85 @@
+/**
+ * Get the current value from a draft (snapshot).
+ * Adapted from mutative - simplified for plain objects/arrays only.
+ */
+
+import type { Draft } from "./interface"
+import {
+  forEach,
+  get,
+  getProxyDraft,
+  isDraft,
+  isDraftable,
+  isEqual,
+  set,
+  shallowCopy,
+} from "./utils"
+
+/**
+ * Get current state from a value (handles nested drafts)
+ */
+function getCurrent<T>(target: T): T {
+  const proxyDraft = getProxyDraft(target)
+
+  // Not draftable - return as-is
+  if (!isDraftable(target)) return target
+
+  // Draft that hasn't been modified - return original
+  if (proxyDraft && !proxyDraft.operated) {
+    return proxyDraft.original as T
+  }
+
+  let currentValue: T | undefined
+
+  function ensureShallowCopyLocal() {
+    currentValue = shallowCopy(target)
+  }
+
+  if (proxyDraft) {
+    // It's a draft - create a shallow copy eagerly
+    proxyDraft.finalized = true
+    try {
+      ensureShallowCopyLocal()
+    } finally {
+      proxyDraft.finalized = false
+    }
+  } else {
+    // Not a draft - use target directly, copy lazily if needed
+    currentValue = target
+  }
+
+  // Recursively process children
+  forEach(currentValue as object, (key, value) => {
+    if (proxyDraft && isEqual(get(proxyDraft.original as object, key), value)) {
+      return
+    }
+    const newValue = getCurrent(value)
+    if (newValue !== value) {
+      if (currentValue === target) {
+        ensureShallowCopyLocal()
+      }
+      set(currentValue as object, key, newValue)
+    }
+  })
+
+  return currentValue as T
+}
+
+/**
+ * `current(draft)` to get current state in the draft mutation function.
+ *
+ * @example
+ * ```ts
+ * const { nextState, ops } = createOps(baseState, (draft) => {
+ *   draft.foo.bar = 'new value';
+ *   console.log(current(draft.foo)); // { bar: 'new value' }
+ * });
+ * ```
+ */
+export function current<T extends object>(target: Draft<T>): T
+export function current<T extends object>(target: T | Draft<T>): T {
+  if (!isDraft(target)) {
+    throw new Error(`current() is only used for Draft, parameter: ${target}`)
+  }
+  return getCurrent(target) as T
+}