@homeostate/core 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @homeostate/core
 
+## 0.1.2
+
+### Patch Changes
+
+- 30abf27: Remove draft release warnings, update docs links
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -1,8 +1,5 @@
 # @homeostate/core
 
-> **Draft / placeholder release.** `0.0.0` reserves the name while the API is still
-> being designed. Nothing here is stable — do not depend on it yet.
-
 State-manager and CRDT-backend agnostic sync engine. It keeps a store, reached through a
 `StoreAdapter`, in sync with a `CrdtBackend` such as
 [`@homeostate/crdt-yjs`](https://github.com/mixedrays/homeostate/tree/main/packages/crdt-yjs),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeostate/core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "State-manager and CRDT-backend agnostic sync engine between a store adapter and a CrdtBackend",
   "license": "MIT",
   "type": "module",
@@ -9,7 +9,7 @@
     "url": "git+https://github.com/mixedrays/homeostate.git",
     "directory": "packages/core"
   },
-  "homepage": "https://github.com/mixedrays/homeostate#readme",
+  "homepage": "https://homeostate.pages.dev",
   "bugs": {
     "url": "https://github.com/mixedrays/homeostate/issues"
   },
@@ -29,6 +29,8 @@
   },
   "files": [
     "dist",
+    "src",
+    "!src/**/__tests__",
     "README.md",
     "LICENSE",
     "THIRD_PARTY_NOTICES.md",

package/src/apply.ts

@@ -0,0 +1,87 @@
+import { ChangeType, type Change } from "./change.js";
+
+type Plain = Record<string, unknown>;
+
+/**
+ * How one store writes into its containers. `applyChanges` decides *what* to write; an
+ * implementation of this decides *how*, so the same edit script drives a MobX observable
+ * tree, a Valtio proxy, or a plain object.
+ *
+ * Every method receives a container that already lives in the store, never a copy.
+ */
+export interface ApplyOps {
+  /** Assign `value` at `key`, creating the property if the target is a record. */
+  set(target: object, key: string | number, value: unknown): void;
+  /** Remove the record property `key`. */
+  remove(target: object, key: string): void;
+  /** `Array.prototype.splice`: drop `deleteCount` elements at `index`, then add `inserted`. */
+  splice(
+    target: unknown[],
+    index: number,
+    deleteCount: number,
+    inserted: unknown[],
+  ): void;
+}
+
+/**
+ * Revises `value` by the character-level edit script `changes`, which is what `getChanges`
+ * returns for two strings. Each index addresses the string as revised by the steps before it.
+ */
+export const applyStringChanges = (value: string, changes: Change[]): string =>
+  changes.reduce((revised, [type, index, inserted]) => {
+    const at = index as number;
+    if (type === ChangeType.INSERT)
+      return revised.slice(0, at) + (inserted as string) + revised.slice(at);
+    if (type === ChangeType.DELETE)
+      return revised.slice(0, at) + revised.slice(at + 1);
+    return revised;
+  }, value);
+
+/**
+ * Applies `changes` to `target` in place, mutating only the paths the edit script names.
+ * Everything else keeps its identity, which is what fine-grained stores react to.
+ *
+ * `changes` must be `getChanges(before, after)` where `before` describes the shape `target`
+ * currently holds — an adapter gets that by diffing against the snapshot it last handed out.
+ * A `PENDING` step carries no replacement value, so it can only be followed by recursing into
+ * the container already there; a target that does not mirror `before` leaves such a step
+ * unapplied rather than writing something wrong.
+ *
+ * @param target The container to mutate — a record, or an array for a positional edit script.
+ * @param changes The edit script to apply, in order.
+ * @param ops How this store writes; see {@link ApplyOps}.
+ */
+export const applyChanges = (
+  target: object,
+  changes: Change[],
+  ops: ApplyOps,
+): void => {
+  const array = Array.isArray(target) ? (target as unknown[]) : null;
+
+  for (const [type, key, value] of changes) {
+    switch (type) {
+      case ChangeType.PENDING: {
+        const child = (target as Plain)[key as string];
+        if (typeof child === "string")
+          ops.set(target, key, applyStringChanges(child, value as Change[]));
+        else if (child !== null && typeof child === "object")
+          applyChanges(child, value as Change[], ops);
+        break;
+      }
+
+      case ChangeType.DELETE:
+        if (array) ops.splice(array, key as number, 1, []);
+        else ops.remove(target, key as string);
+        break;
+
+      case ChangeType.INSERT:
+        if (array) ops.splice(array, key as number, 0, [value]);
+        else ops.set(target, key, value);
+        break;
+
+      case ChangeType.UPDATE:
+        ops.set(target, key, value);
+        break;
+    }
+  }
+};

package/src/change.ts

@@ -0,0 +1,23 @@
+/**
+ * Describes the change that needs to be made.
+ */
+export enum ChangeType {
+  /** A value was inserted. */
+  INSERT = "insert",
+  /** A value was replaced. */
+  UPDATE = "update",
+  /** A value was deleted. */
+  DELETE = "delete",
+  /** The value requires a recursive diff to identify further changes. */
+  PENDING = "pending",
+}
+
+/**
+ * One step in turning a container into another: `[type, key, value]`.
+ *
+ * Steps apply in order. A numeric key addresses the array or string as revised by the
+ * steps before it, so appliers never sort or clamp. `value` is the inserted or replacing
+ * value (a string insert may carry several characters), `undefined` for a delete, and the
+ * nested `Change[]` for a pending entry.
+ */
+export type Change = [ChangeType, string | number, unknown];

package/src/diff.ts

@@ -0,0 +1,229 @@
+import { ChangeType, type Change } from "./change.js";
+
+export type Diffable = Record<string, unknown> | Array<unknown> | string;
+
+const isArray = (value: unknown): value is Array<unknown> =>
+  Array.isArray(value);
+
+const isString = (value: unknown): value is string => typeof value === "string";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+const isDiffable = (value: unknown): value is Diffable =>
+  isArray(value) || isString(value) || isRecord(value);
+
+const isSameKind = (a: Diffable, b: Diffable): boolean =>
+  isString(a) ? isString(b) : isArray(a) ? isArray(b) : isRecord(b);
+
+const nestedChanges = (a: unknown, b: unknown): Change[] | null =>
+  isDiffable(a) && isDiffable(b) && isSameKind(a, b) ? getChanges(a, b) : null;
+
+const deepEqual = (a: unknown, b: unknown): boolean => {
+  if (a === b) return true;
+  if (isArray(a) && isArray(b))
+    return (
+      a.length === b.length && a.every((value, i) => deepEqual(value, b[i]))
+    );
+  if (isRecord(a) && isRecord(b)) {
+    const keys = Object.keys(a);
+    return (
+      keys.length === Object.keys(b).length &&
+      keys.every((key) => key in b && deepEqual(a[key], b[key]))
+    );
+  }
+  return false;
+};
+
+export const getChanges = (a: Diffable, b: Diffable): Change[] => {
+  if (isString(a) && isString(b)) return getStringChanges(a, b);
+  if (isArray(a) && isArray(b)) return getArrayChanges(a, b);
+  if (isRecord(a) && isRecord(b)) return getRecordChanges(a, b);
+  return [];
+};
+
+const sharesCharacter = (a: string, b: string): boolean => {
+  const characters = new Set(a);
+  for (const character of b) if (characters.has(character)) return true;
+  return false;
+};
+
+const getStringChanges = (a: string, b: string): Change[] => {
+  if (a === b) return [];
+  if (!sharesCharacter(a, b)) {
+    const deletes = Array.from(a, (): Change => [
+      ChangeType.DELETE,
+      0,
+      undefined,
+    ]);
+    return b.length === 0 ? deletes : [...deletes, [ChangeType.INSERT, 0, b]];
+  }
+
+  const changes: Change[] = [];
+  let index = 0;
+
+  for (const { step, b: position } of editScript(a, b, (x, y) => x === y)) {
+    if (step === "eq") index++;
+    else if (step === "del")
+      changes.push([ChangeType.DELETE, index, undefined]);
+    else {
+      const last = changes.length > 0 ? changes[changes.length - 1] : undefined;
+      if (
+        last !== undefined &&
+        last[0] === ChangeType.INSERT &&
+        (last[1] as number) + (last[2] as string).length === index
+      ) {
+        last[2] = (last[2] as string) + b[position];
+      } else changes.push([ChangeType.INSERT, index, b[position]]);
+      index++;
+    }
+  }
+
+  return changes;
+};
+
+const getArrayChanges = (a: Array<unknown>, b: Array<unknown>): Change[] => {
+  const changes: Change[] = [];
+  let index = 0;
+  let deleted: number[] = [];
+  let inserted: number[] = [];
+
+  const flush = (): void => {
+    const pairs = Math.min(deleted.length, inserted.length);
+    for (let i = 0; i < pairs; i++) {
+      const next = b[inserted[i]];
+      const nested = nestedChanges(a[deleted[i]], next);
+      if (nested === null) changes.push([ChangeType.UPDATE, index, next]);
+      else if (nested.length > 0)
+        changes.push([ChangeType.PENDING, index, nested]);
+      index++;
+    }
+    for (let i = pairs; i < deleted.length; i++)
+      changes.push([ChangeType.DELETE, index, undefined]);
+    for (let i = pairs; i < inserted.length; i++) {
+      changes.push([ChangeType.INSERT, index, b[inserted[i]]]);
+      index++;
+    }
+    deleted = [];
+    inserted = [];
+  };
+
+  for (const { step, a: from, b: to } of editScript(a, b, deepEqual)) {
+    if (step === "del") deleted.push(from);
+    else if (step === "ins") inserted.push(to);
+    else {
+      flush();
+      index++;
+    }
+  }
+  flush();
+
+  return changes;
+};
+
+const getRecordChanges = (
+  a: Record<string, unknown>,
+  b: Record<string, unknown>,
+): Change[] => {
+  const changes: Change[] = [];
+
+  for (const property of Object.keys(a))
+    if (!(property in b))
+      changes.push([ChangeType.DELETE, property, undefined]);
+
+  for (const [property, value] of Object.entries(b)) {
+    if (!(property in a)) changes.push([ChangeType.INSERT, property, value]);
+    else {
+      const nested = nestedChanges(a[property], value);
+      if (nested === null) {
+        if (a[property] !== value)
+          changes.push([ChangeType.UPDATE, property, value]);
+      } else if (nested.length > 0)
+        changes.push([ChangeType.PENDING, property, nested]);
+    }
+  }
+
+  return changes;
+};
+
+interface EditOp {
+  step: "eq" | "ins" | "del";
+  a: number;
+  b: number;
+}
+
+/**
+ * Shortest edit script from `a` to `b` by Wu et al.'s O(NP) algorithm. Adapted from
+ * https://github.com/cubicdaiya/onp/blob/master/javascript/onp.js.
+ */
+const editScript = <T>(
+  a: ArrayLike<T>,
+  b: ArrayLike<T>,
+  equal: (x: T, y: T) => boolean,
+): EditOp[] => {
+  const swapped = a.length > b.length;
+  const s = swapped ? b : a;
+  const t = swapped ? a : b;
+  const m = s.length;
+  const n = t.length;
+  const delta = n - m;
+  const offset = m + 1;
+  const furthest = new Array<number>(m + n + 3).fill(-1);
+  const pointAt = new Array<number>(m + n + 3).fill(-1);
+  const points: { x: number; y: number; prev: number }[] = [];
+
+  const snake = (k: number): void => {
+    const fromBelow = furthest[k + offset - 1] + 1;
+    const fromAbove = furthest[k + offset + 1];
+    let y = Math.max(fromBelow, fromAbove);
+    let x = y - k;
+    while (x < m && y < n && equal(s[x], t[y])) {
+      x++;
+      y++;
+    }
+    furthest[k + offset] = y;
+    pointAt[k + offset] = points.length;
+    points.push({
+      x,
+      y,
+      prev:
+        fromBelow > fromAbove
+          ? pointAt[k + offset - 1]
+          : pointAt[k + offset + 1],
+    });
+  };
+
+  for (let p = 0; furthest[delta + offset] !== n; p++) {
+    for (let k = -p; k < delta; k++) snake(k);
+    for (let k = delta + p; k > delta; k--) snake(k);
+    snake(delta);
+  }
+
+  const path: { x: number; y: number }[] = [];
+  for (let i = pointAt[delta + offset]; i !== -1; i = points[i].prev)
+    path.push(points[i]);
+
+  const ops: EditOp[] = [];
+  let x = 0;
+  let y = 0;
+  const op = (step: EditOp["step"]): EditOp =>
+    swapped ? { step, a: y, b: x } : { step, a: x, b: y };
+
+  for (let i = path.length - 1; i >= 0; i--) {
+    const end = path[i];
+    if (end.y - end.x > y - x) {
+      ops.push(op(swapped ? "del" : "ins"));
+      y++;
+    } else if (end.y - end.x < y - x) {
+      ops.push(op(swapped ? "ins" : "del"));
+      x++;
+    }
+    while (x < end.x) {
+      ops.push(op("eq"));
+      x++;
+      y++;
+    }
+  }
+
+  return ops;
+};

package/src/index.ts

@@ -0,0 +1,18 @@
+export { createSyncEngine } from "./sync-engine.js";
+export { createMemoryBackend } from "./memory-backend.js";
+export type { MemoryBackend } from "./memory-backend.js";
+export { getChanges } from "./diff.js";
+export { applyChanges, applyStringChanges } from "./apply.js";
+export type { ApplyOps } from "./apply.js";
+export type { Diffable } from "./diff.js";
+export { ChangeType } from "./change.js";
+export type { Change } from "./change.js";
+export { defaultSyncFilter } from "./types.js";
+export type {
+  CrdtBackend,
+  SeedStrategy,
+  StoreAdapter,
+  SyncEngine,
+  SyncEngineConfig,
+  Unsubscribe,
+} from "./types.js";

package/src/memory-backend.ts

@@ -0,0 +1,38 @@
+import type { CrdtBackend, Unsubscribe } from "./types.js";
+
+export interface MemoryBackend extends CrdtBackend {
+  /** Replace the held state as if a remote peer had written it, then notify subscribers */
+  receive: (next: unknown) => void;
+}
+
+const clone = <T>(value: T): T =>
+  value === undefined ? value : JSON.parse(JSON.stringify(value));
+
+/**
+ * Plain-JSON backend with no replication. It proves the engine has no
+ * CRDT-library assumptions and gives tests a fast in-process peer.
+ */
+export const createMemoryBackend = (initial: unknown = {}): MemoryBackend => {
+  let state = clone(initial);
+  const listeners = new Set<() => void>();
+
+  return {
+    read: () => clone(state),
+
+    write: (next) => {
+      state = clone(next);
+    },
+
+    subscribe: (onRemoteChange): Unsubscribe => {
+      listeners.add(onRemoteChange);
+      return () => {
+        listeners.delete(onRemoteChange);
+      };
+    },
+
+    receive: (next) => {
+      state = clone(next);
+      listeners.forEach((listener) => listener());
+    },
+  };
+};

package/src/patching.ts

@@ -0,0 +1,86 @@
+import { applyStringChanges } from "./apply.js";
+import { ChangeType, type Change } from "./change.js";
+import { getChanges, type Diffable } from "./diff.js";
+
+const applyChanges = (state: Diffable, changes: Change[]): Diffable => {
+  if (typeof state === "string") return applyStringChanges(state, changes);
+  if (Array.isArray(state)) return applyChangesToArray(state, changes);
+  return applyChangesToObject(state, changes);
+};
+
+const applyChangesToArray = (
+  array: unknown[],
+  changes: Change[],
+): unknown[] => {
+  const revised = [...array];
+
+  for (const [type, index, value] of changes) {
+    const i = index as number;
+
+    switch (type) {
+      case ChangeType.INSERT:
+        revised.splice(i, 0, value);
+        break;
+
+      case ChangeType.UPDATE:
+        revised[i] = value;
+        break;
+
+      case ChangeType.PENDING:
+        revised[i] = applyChanges(revised[i] as Diffable, value as Change[]);
+        break;
+
+      case ChangeType.DELETE:
+        revised.splice(i, 1);
+        break;
+    }
+  }
+
+  return revised;
+};
+
+const applyChangesToObject = (
+  object: Record<string, unknown>,
+  changes: Change[],
+): Record<string, unknown> => {
+  const revised = { ...object };
+
+  for (const [type, property, value] of changes) {
+    const key = property as string;
+
+    switch (type) {
+      case ChangeType.INSERT:
+      case ChangeType.UPDATE:
+        revised[key] = value;
+        break;
+
+      case ChangeType.PENDING:
+        revised[key] = applyChanges(object[key] as Diffable, value as Change[]);
+        break;
+
+      case ChangeType.DELETE:
+        delete revised[key];
+        break;
+    }
+  }
+
+  return revised;
+};
+
+/**
+ * Returns a value identical to newState, built from oldState by copying every
+ * container along a changed path and sharing every unchanged subtree. Neither
+ * input is mutated. If oldState and newState are already identical (indicated
+ * by an empty diff), then oldState itself is returned.
+ *
+ * @param oldState The state we want to patch.
+ * @param newState The state we want the result to match.
+ *
+ * @returns The patched state, identical to newState.
+ */
+export const patchState = <T>(oldState: T, newState: T): T => {
+  const changes = getChanges(oldState as Diffable, newState as Diffable);
+
+  if (changes.length === 0) return oldState;
+  return applyChanges(oldState as Diffable, changes) as T;
+};

package/src/sync-engine.ts

@@ -0,0 +1,135 @@
+import type {
+  CrdtBackend,
+  StoreAdapter,
+  SyncEngine,
+  SyncEngineConfig,
+  Unsubscribe,
+} from "./types.js";
+import { defaultSyncFilter } from "./types.js";
+import { patchState } from "./patching.js";
+
+type Plain = Record<string, unknown>;
+
+/**
+ * Creates a sync engine that keeps a store (via its adapter) and a CRDT backend
+ * in sync in both directions.
+ *
+ * This is the core abstraction that makes the sync logic state-manager and
+ * CRDT-library agnostic.
+ *
+ * On `connect()` the two sides are reconciled per key over the filtered view: a key the
+ * backend holds wins over the store's value, and a synced key the backend lacks stays in
+ * the store and is seeded into the backend unless `seed` is `'never'`. Afterwards the
+ * backend owns the synced document: every write replaces it with the store's filtered
+ * state, and a key removed from the backend is removed from the store.
+ *
+ * @example
+ * ```typescript
+ * const backend = createYjsBackend(new Y.Doc(), 'shared');
+ * const adapter = new ZustandAdapter(store);
+ * const engine = createSyncEngine(backend, adapter);
+ * engine.connect();
+ * ```
+ */
+export function createSyncEngine<S extends object>(
+  backend: CrdtBackend,
+  adapter: StoreAdapter<S>,
+  config: SyncEngineConfig = {},
+): SyncEngine {
+  const { filter = defaultSyncFilter, seed = "if-empty" } = config;
+
+  let connected = false;
+  let storeUnsubscribe: Unsubscribe | null = null;
+  let backendUnsubscribe: Unsubscribe | null = null;
+  let applyingRemote = false;
+
+  const filterState = (state: object): Plain => {
+    const filtered: Plain = {};
+    for (const [key, value] of Object.entries(state)) {
+      if (filter(key, value)) filtered[key] = value;
+    }
+    return filtered;
+  };
+
+  const readBackend = (): Plain => {
+    const value = backend.read();
+    return value !== null && typeof value === "object" ? (value as Plain) : {};
+  };
+
+  /**
+   * Builds the next store state from `remote`. With `keepLocalOnly`, a synced key the
+   * backend does not hold is left in place instead of being deleted; that is the
+   * connect-time reconciliation. Otherwise `remote` is the whole synced state.
+   */
+  const mergeStates = (
+    current: S,
+    remote: Plain,
+    keepLocalOnly: boolean,
+  ): S => {
+    const synced = filterState(current);
+    const target = keepLocalOnly ? { ...synced, ...remote } : remote;
+    const patched = patchState(synced, target);
+    if (patched === synced) return current;
+
+    const merged: Plain = { ...current, ...patched };
+    for (const key of Object.keys(synced)) {
+      if (!(key in patched)) delete merged[key];
+    }
+    return merged as S;
+  };
+
+  const syncToBackend = (): void => {
+    if (applyingRemote) return;
+    backend.write(filterState(adapter.getState()));
+  };
+
+  const applyRemote = (remote: Plain, keepLocalOnly: boolean): void => {
+    applyingRemote = true;
+    try {
+      const current = adapter.getState();
+      const merged = mergeStates(current, remote, keepLocalOnly);
+      if (merged !== current) adapter.setState(merged);
+    } finally {
+      applyingRemote = false;
+    }
+  };
+
+  const syncToStore = (): void => {
+    applyRemote(filterState(readBackend()), false);
+  };
+
+  return {
+    connect: (): void => {
+      if (connected) return;
+
+      const remote = filterState(readBackend());
+      const local = filterState(adapter.getState());
+      const remoteKeys = new Set(Object.keys(remote));
+      const missing = Object.keys(local).filter((key) => !remoteKeys.has(key));
+
+      if (seed === "if-empty" && missing.length > 0) {
+        const seeded: Plain = { ...remote };
+        for (const key of missing) seeded[key] = local[key];
+        backend.write(seeded);
+      }
+
+      applyRemote(remote, true);
+
+      backendUnsubscribe = backend.subscribe(syncToStore);
+      storeUnsubscribe = adapter.subscribe(syncToBackend);
+      connected = true;
+    },
+
+    disconnect: (): void => {
+      if (!connected) return;
+
+      backendUnsubscribe?.();
+      backendUnsubscribe = null;
+      storeUnsubscribe?.();
+      storeUnsubscribe = null;
+      connected = false;
+    },
+
+    isConnected: (): boolean => connected,
+  };
+}

package/src/types.ts

@@ -0,0 +1,98 @@
+/**
+ * Core types for the state-manager and CRDT-backend agnostic sync engine.
+ * These interfaces let any store be kept in sync through any replicated backend.
+ */
+
+/**
+ * Unsubscribe function returned by subscribe
+ */
+export type Unsubscribe = () => void;
+
+/**
+ * Adapter interface that bridges a specific state manager with the sync engine.
+ * Implement this interface to add support for any state manager (Zustand, Redux, MobX, etc.)
+ *
+ * State must be plain JSON: objects, arrays, strings, numbers, booleans, and null.
+ * Functions are dropped by the default filter; other values such as Date, Map, or Set
+ * are neither diffed nor synced.
+ */
+export interface StoreAdapter<S extends object> {
+  /** Get the current state from the store */
+  getState: () => S;
+
+  /**
+   * Replace the store state. Called only for changes coming from the backend; the
+   * engine ignores store notifications raised while it runs, so the adapter needs no
+   * echo suppression of its own.
+   */
+  setState: (state: S) => void;
+
+  /**
+   * Subscribe to store changes that should be written to the backend.
+   * @returns Unsubscribe function
+   */
+  subscribe: (onStoreChange: () => void) => Unsubscribe;
+}
+
+/**
+ * Backend that holds the synced subtree in a CRDT or any other replicated store.
+ * The engine only ever exchanges plain JSON with it.
+ */
+export interface CrdtBackend {
+  /** Plain JSON snapshot of the synced subtree. Must not alias backend internals. */
+  read: () => unknown;
+
+  /**
+   * Make the backend equal to `next` in one atomic transaction.
+   * The backend decides the granularity of the operations; `getChanges` is exported for that.
+   */
+  write: (next: unknown) => void;
+
+  /**
+   * Notify about changes that did not come through this backend's own `write`.
+   * @returns Unsubscribe function
+   */
+  subscribe: (onRemoteChange: () => void) => Unsubscribe;
+}
+
+/**
+ * Whether `connect()` may write the store's synced keys that the backend does not hold.
+ * Reconciliation is per key over the filtered view: a key the backend holds always wins
+ * over the store's value, a key only the store holds always stays in the store.
+ * - `'if-empty'`: seed the keys the backend lacks, in one write (default)
+ * - `'never'`: leave seeding to the caller; the keys are written on the next local change
+ */
+export type SeedStrategy = "if-empty" | "never";
+
+/**
+ * Configuration options for the sync engine
+ */
+export interface SyncEngineConfig {
+  /**
+   * Filter function to determine which state keys should be synced, in both directions.
+   * Return true to sync the key, false to exclude it.
+   * By default, functions are excluded from sync.
+   */
+  filter?: (key: string, value: unknown) => boolean;
+  /** Seeding strategy used by `connect()`; defaults to `'if-empty'` */
+  seed?: SeedStrategy;
+}
+
+/**
+ * The sync engine interface - manages bidirectional sync between a store and a backend
+ */
+export interface SyncEngine {
+  /** Start synchronization */
+  connect: () => void;
+  /** Stop synchronization and cleanup */
+  disconnect: () => void;
+  /** Check if engine is connected */
+  isConnected: () => boolean;
+}
+
+/**
+ * Default filter that excludes functions from sync
+ */
+export const defaultSyncFilter = (_key: string, value: unknown): boolean => {
+  return typeof value !== "function";
+};