@strata-sync/client 0.1.0

package/tests/reverse-linear-sync-engine.test.ts

@@ -0,0 +1,701 @@
+import { describe, expect, it } from "vitest";
+import {
+  type BatchLoadOptions,
+  type BootstrapMetadata,
+  type BootstrapOptions,
+  type ConnectionState,
+  type DeltaPacket,
+  type DeltaSubscription,
+  type ModelRegistrySnapshot,
+  type ModelRow,
+  type MutateResult,
+  noopReactivityAdapter,
+  type SchemaDefinition,
+  type SubscribeOptions,
+  type SyncAction,
+  type Transaction,
+  type TransactionBatch,
+} from "../../sync-core/src/index";
+import { createSyncClient } from "../src/index";
+import type {
+  ModelPersistenceMeta,
+  StorageAdapter,
+  StorageMeta,
+  TransportAdapter,
+} from "../src/types";
+
+class InMemoryStorage implements StorageAdapter {
+  private readonly data = new Map<
+    string,
+    Map<string, Record<string, unknown>>
+  >();
+  private meta: StorageMeta = { lastSyncId: 0 };
+  private readonly modelPersistence = new Map<string, boolean>();
+  private readonly outbox: Transaction[] = [];
+  private readonly partialIndexes = new Set<string>();
+  private readonly syncActions: SyncAction[] = [];
+
+  open(_options: {
+    name?: string;
+    userId?: string;
+    version?: number;
+    userVersion?: number;
+    schema?: SchemaDefinition | ModelRegistrySnapshot;
+  }): Promise<void> {
+    return Promise.resolve();
+  }
+
+  close(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  private getModelStore(
+    modelName: string
+  ): Map<string, Record<string, unknown>> {
+    const existing = this.data.get(modelName);
+    if (existing) {
+      return existing;
+    }
+    const created = new Map<string, Record<string, unknown>>();
+    this.data.set(modelName, created);
+    return created;
+  }
+
+  get<T>(modelName: string, id: string): Promise<T | null> {
+    const store = this.data.get(modelName);
+    if (!store) {
+      return Promise.resolve(null);
+    }
+    return Promise.resolve((store.get(id) as T | undefined) ?? null);
+  }
+
+  getAll<T>(modelName: string): Promise<T[]> {
+    const store = this.data.get(modelName);
+    if (!store) {
+      return Promise.resolve([]);
+    }
+    return Promise.resolve(Array.from(store.values()) as T[]);
+  }
+
+  put<T extends Record<string, unknown>>(
+    modelName: string,
+    row: T
+  ): Promise<void> {
+    const id = row.id;
+    if (typeof id !== "string") {
+      throw new Error(`Missing id for model ${modelName}`);
+    }
+    const store = this.getModelStore(modelName);
+    store.set(id, { ...row });
+    return Promise.resolve();
+  }
+
+  delete(modelName: string, id: string): Promise<void> {
+    this.data.get(modelName)?.delete(id);
+    return Promise.resolve();
+  }
+
+  getByIndex<T>(
+    modelName: string,
+    indexName: string,
+    key: string
+  ): Promise<T[]> {
+    const store = this.data.get(modelName);
+    if (!store) {
+      return Promise.resolve([]);
+    }
+    const results: T[] = [];
+    for (const row of store.values()) {
+      if (row[indexName] === key) {
+        results.push(row as T);
+      }
+    }
+    return Promise.resolve(results);
+  }
+
+  async writeBatch(
+    ops: Array<{
+      type: "put" | "delete";
+      modelName: string;
+      id?: string;
+      data?: Record<string, unknown>;
+    }>
+  ): Promise<void> {
+    for (const op of ops) {
+      if (op.type === "put" && op.data) {
+        await this.put(op.modelName, op.data);
+        continue;
+      }
+      if (op.type === "delete" && op.id) {
+        await this.delete(op.modelName, op.id);
+      }
+    }
+  }
+
+  getMeta(): Promise<StorageMeta> {
+    const subscribedSyncGroups = this.meta.subscribedSyncGroups;
+    return Promise.resolve({
+      ...this.meta,
+      subscribedSyncGroups: Array.isArray(subscribedSyncGroups)
+        ? [...subscribedSyncGroups]
+        : undefined,
+    });
+  }
+
+  setMeta(meta: Partial<StorageMeta>): Promise<void> {
+    const subscribedSyncGroups = meta.subscribedSyncGroups;
+    this.meta = {
+      ...this.meta,
+      ...meta,
+      subscribedSyncGroups: Array.isArray(subscribedSyncGroups)
+        ? [...subscribedSyncGroups]
+        : this.meta.subscribedSyncGroups,
+    };
+    return Promise.resolve();
+  }
+
+  getModelPersistence(modelName: string): Promise<ModelPersistenceMeta> {
+    return Promise.resolve({
+      modelName,
+      persisted: this.modelPersistence.get(modelName) ?? false,
+    });
+  }
+
+  setModelPersistence(modelName: string, persisted: boolean): Promise<void> {
+    this.modelPersistence.set(modelName, persisted);
+    return Promise.resolve();
+  }
+
+  getOutbox(): Promise<Transaction[]> {
+    return Promise.resolve([...this.outbox]);
+  }
+
+  addToOutbox(tx: Transaction): Promise<void> {
+    this.outbox.push(tx);
+    return Promise.resolve();
+  }
+
+  removeFromOutbox(clientTxId: string): Promise<void> {
+    const index = this.outbox.findIndex((tx) => tx.clientTxId === clientTxId);
+    if (index >= 0) {
+      this.outbox.splice(index, 1);
+    }
+    return Promise.resolve();
+  }
+
+  updateOutboxTransaction(
+    clientTxId: string,
+    updates: Partial<Transaction>
+  ): Promise<void> {
+    const tx = this.outbox.find((entry) => entry.clientTxId === clientTxId);
+    if (tx) {
+      Object.assign(tx, updates);
+    }
+    return Promise.resolve();
+  }
+
+  hasPartialIndex(
+    modelName: string,
+    indexedKey: string,
+    keyValue: string
+  ): Promise<boolean> {
+    return Promise.resolve(
+      this.partialIndexes.has(`${modelName}:${indexedKey}:${keyValue}`)
+    );
+  }
+
+  setPartialIndex(
+    modelName: string,
+    indexedKey: string,
+    keyValue: string
+  ): Promise<void> {
+    this.partialIndexes.add(`${modelName}:${indexedKey}:${keyValue}`);
+    return Promise.resolve();
+  }
+
+  addSyncActions(actions: SyncAction[]): Promise<void> {
+    this.syncActions.push(...actions);
+    return Promise.resolve();
+  }
+
+  getSyncActions(afterSyncId?: number, limit?: number): Promise<SyncAction[]> {
+    const filtered = afterSyncId
+      ? this.syncActions.filter((action) => action.id > afterSyncId)
+      : [...this.syncActions];
+    if (typeof limit === "number") {
+      return Promise.resolve(filtered.slice(0, limit));
+    }
+    return Promise.resolve(filtered);
+  }
+
+  clearSyncActions(): Promise<void> {
+    this.syncActions.length = 0;
+    return Promise.resolve();
+  }
+
+  clear(): Promise<void> {
+    this.data.clear();
+    this.modelPersistence.clear();
+    this.outbox.length = 0;
+    this.partialIndexes.clear();
+    this.syncActions.length = 0;
+    this.meta = { lastSyncId: 0 };
+    return Promise.resolve();
+  }
+
+  count(modelName: string): Promise<number> {
+    return Promise.resolve(this.data.get(modelName)?.size ?? 0);
+  }
+}
+
+class AsyncQueue<T> implements AsyncIterable<T> {
+  private readonly items: T[] = [];
+  private readonly resolvers: Array<(result: IteratorResult<T>) => void> = [];
+  private closed = false;
+
+  push(item: T): void {
+    if (this.closed) {
+      return;
+    }
+    const resolver = this.resolvers.shift();
+    if (resolver) {
+      resolver({ value: item, done: false });
+      return;
+    }
+    this.items.push(item);
+  }
+
+  close(): void {
+    this.closed = true;
+    for (const resolver of this.resolvers.splice(0)) {
+      resolver({ value: undefined as T, done: true });
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    return {
+      next: (): Promise<IteratorResult<T>> => {
+        const item = this.items.shift();
+        if (item !== undefined) {
+          return Promise.resolve({ value: item, done: false });
+        }
+        if (this.closed) {
+          return Promise.resolve({ value: undefined as T, done: true });
+        }
+        return new Promise((resolve) => {
+          this.resolvers.push(resolve);
+        });
+      },
+      return: (): Promise<IteratorResult<T>> => {
+        this.close();
+        return Promise.resolve({ value: undefined as T, done: true });
+      },
+    };
+  }
+}
+
+class TestTransport implements TransportAdapter {
+  private readonly deltaQueue = new AsyncQueue<DeltaPacket>();
+  private readonly fullRows: ModelRow[];
+  private readonly fullMetadata: BootstrapMetadata;
+  private readonly partialRowsByGroup: Map<string, ModelRow[]>;
+  private readonly connectionListeners = new Set<
+    (state: ConnectionState) => void
+  >();
+  private readonly connectionState: ConnectionState = "connected";
+  private nextSyncId: number;
+
+  readonly bootstrapCalls: BootstrapOptions[] = [];
+
+  constructor(options: {
+    fullRows: ModelRow[];
+    fullMetadata: BootstrapMetadata;
+    partialRowsByGroup?: Map<string, ModelRow[]>;
+    startingSyncId?: number;
+  }) {
+    this.fullRows = options.fullRows;
+    this.fullMetadata = options.fullMetadata;
+    this.partialRowsByGroup = options.partialRowsByGroup ?? new Map();
+    this.nextSyncId = options.startingSyncId ?? 100;
+  }
+
+  bootstrap(
+    options: BootstrapOptions
+  ): AsyncGenerator<ModelRow, BootstrapMetadata, unknown> {
+    this.bootstrapCalls.push(options);
+    const isPartial = options.type === "partial";
+    const rows = isPartial
+      ? this.getPartialRows(options.syncGroups ?? [])
+      : this.fullRows;
+    const metadata = isPartial
+      ? { subscribedSyncGroups: options.syncGroups ?? [] }
+      : this.fullMetadata;
+
+    return (async function* generate() {
+      await Promise.resolve();
+      for (const row of rows) {
+        yield row;
+      }
+      return metadata;
+    })();
+  }
+
+  private getPartialRows(groups: string[]): ModelRow[] {
+    const rows: ModelRow[] = [];
+    for (const group of groups) {
+      const groupRows = this.partialRowsByGroup.get(group);
+      if (groupRows) {
+        rows.push(...groupRows);
+      }
+    }
+    return rows;
+  }
+
+  batchLoad(
+    _options: BatchLoadOptions
+  ): AsyncGenerator<ModelRow, void, unknown> {
+    return (async function* () {
+      await Promise.resolve();
+      yield* [];
+    })();
+  }
+
+  mutate(batch: TransactionBatch): Promise<MutateResult> {
+    const results = batch.transactions.map((tx) => {
+      this.nextSyncId += 1;
+      return {
+        clientTxId: tx.clientTxId,
+        success: true,
+        syncId: this.nextSyncId,
+      };
+    });
+
+    return Promise.resolve({
+      success: true,
+      lastSyncId: this.nextSyncId,
+      results,
+    });
+  }
+
+  subscribe(_options: SubscribeOptions): DeltaSubscription {
+    return {
+      [Symbol.asyncIterator]: () => this.deltaQueue[Symbol.asyncIterator](),
+      unsubscribe: () => this.deltaQueue.close(),
+    };
+  }
+
+  emitDelta(packet: DeltaPacket): void {
+    this.deltaQueue.push(packet);
+  }
+
+  fetchDeltas(after: number, _limit?: number): Promise<DeltaPacket> {
+    return Promise.resolve({ lastSyncId: after, actions: [] });
+  }
+
+  getConnectionState(): ConnectionState {
+    return this.connectionState;
+  }
+
+  onConnectionStateChange(
+    callback: (state: ConnectionState) => void
+  ): () => void {
+    this.connectionListeners.add(callback);
+    callback(this.connectionState);
+    return () => {
+      this.connectionListeners.delete(callback);
+    };
+  }
+
+  close(): Promise<void> {
+    this.deltaQueue.close();
+    return Promise.resolve();
+  }
+}
+
+const schema: SchemaDefinition = {
+  models: {
+    Issue: {
+      loadStrategy: "instant",
+      groupKey: "teamId",
+      fields: {
+        id: {},
+        title: {},
+        teamId: {},
+      },
+    },
+    Team: {
+      loadStrategy: "instant",
+      fields: {
+        id: {},
+        name: {},
+      },
+    },
+  },
+};
+
+const waitForSync = async (
+  client: ReturnType<typeof createSyncClient>,
+  expectedSyncId: number
+): Promise<void> => {
+  await new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new Error("Timed out waiting for sync completion"));
+    }, 2000);
+
+    const unsubscribe = client.onEvent((event) => {
+      if (
+        event.type === "syncComplete" &&
+        event.lastSyncId === expectedSyncId
+      ) {
+        clearTimeout(timeout);
+        unsubscribe();
+        resolve();
+      }
+    });
+  });
+};
+
+const waitForOutboxCount = async (
+  client: ReturnType<typeof createSyncClient>,
+  expectedCount: number
+): Promise<void> => {
+  await new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new Error("Timed out waiting for outbox count"));
+    }, 2000);
+
+    const unsubscribe = client.onEvent((event) => {
+      if (
+        event.type === "outboxChange" &&
+        event.pendingCount === expectedCount
+      ) {
+        clearTimeout(timeout);
+        unsubscribe();
+        resolve();
+      }
+    });
+  });
+};
+
+describe("reverse-strata-sync alignment", () => {
+  it("bootstraps metadata and hydrates the object pool", async () => {
+    const storage = new InMemoryStorage();
+    const rows: ModelRow[] = [
+      {
+        modelName: "Issue",
+        data: { id: "issue-1", title: "First", teamId: "team-1" },
+      },
+      {
+        modelName: "Team",
+        data: { id: "team-1", name: "Core" },
+      },
+    ];
+    const transport = new TestTransport({
+      fullRows: rows,
+      fullMetadata: {
+        lastSyncId: 42,
+        subscribedSyncGroups: ["team-1"],
+        databaseVersion: 7,
+      },
+    });
+
+    const client = createSyncClient({
+      storage,
+      transport,
+      reactivity: noopReactivityAdapter,
+      schema,
+    });
+
+    try {
+      await client.start();
+
+      expect(client.lastSyncId).toBe(42);
+      const meta = (await storage.getMeta()) as {
+        lastSyncId?: number;
+        firstSyncId?: number;
+        subscribedSyncGroups?: string[];
+      };
+      expect(meta.lastSyncId).toBe(42);
+      expect(meta.firstSyncId).toBe(42);
+      expect(meta.subscribedSyncGroups).toEqual(["team-1"]);
+
+      const issueMap = client.getIdentityMap<Record<string, unknown>>("Issue");
+      expect(issueMap.get("issue-1")).toMatchObject({
+        id: "issue-1",
+        title: "First",
+      });
+
+      const persistence = await storage.getModelPersistence("Issue");
+      expect(persistence.persisted).toBe(true);
+
+      expect(transport.bootstrapCalls[0]?.onlyModels).toEqual([
+        "Issue",
+        "Team",
+      ]);
+    } finally {
+      await client.stop();
+    }
+  });
+
+  it("applies delta packets and clears confirmed outbox transactions", async () => {
+    const storage = new InMemoryStorage();
+    const rows: ModelRow[] = [
+      {
+        modelName: "Issue",
+        data: { id: "issue-1", title: "Seed", teamId: "team-1" },
+      },
+      {
+        modelName: "Team",
+        data: { id: "team-1", name: "Core" },
+      },
+    ];
+    const transport = new TestTransport({
+      fullRows: rows,
+      fullMetadata: {
+        lastSyncId: 10,
+        subscribedSyncGroups: ["team-1"],
+      },
+      startingSyncId: 50,
+    });
+
+    const client = createSyncClient({
+      storage,
+      transport,
+      reactivity: noopReactivityAdapter,
+      schema,
+      batchMutations: false,
+    });
+
+    try {
+      await client.start();
+
+      let createdTx: Transaction | null = null;
+      const created = await client.create(
+        "Issue",
+        { id: "issue-2", title: "New", teamId: "team-1" },
+        {
+          onTransactionCreated: (tx) => {
+            createdTx = tx;
+          },
+        }
+      );
+
+      expect(createdTx).not.toBeNull();
+      const outbox = await storage.getOutbox();
+      expect(outbox).toHaveLength(1);
+      expect(outbox[0]?.state).toBe("awaitingSync");
+
+      const syncId = outbox[0]?.syncIdNeededForCompletion ?? 51;
+      const delta: DeltaPacket = {
+        lastSyncId: syncId,
+        actions: [
+          {
+            id: syncId,
+            action: "I",
+            modelName: "Issue",
+            modelId: "issue-2",
+            data: created,
+            clientTxId: createdTx?.clientTxId,
+          },
+        ],
+      };
+
+      const syncWaiter = waitForSync(client, syncId);
+      const outboxWaiter = waitForOutboxCount(client, 0);
+      transport.emitDelta(delta);
+      await Promise.all([syncWaiter, outboxWaiter]);
+
+      const clearedOutbox = await storage.getOutbox();
+      expect(clearedOutbox).toHaveLength(0);
+
+      const issueMap = client.getIdentityMap<Record<string, unknown>>("Issue");
+      expect(issueMap.get("issue-2")).toMatchObject({
+        id: "issue-2",
+        title: "New",
+      });
+    } finally {
+      await client.stop();
+    }
+  });
+
+  it("sync-group deltas trigger partial bootstrap for new groups", async () => {
+    const storage = new InMemoryStorage();
+    const rows: ModelRow[] = [
+      {
+        modelName: "Issue",
+        data: { id: "issue-1", title: "Seed", teamId: "team-1" },
+      },
+      {
+        modelName: "Team",
+        data: { id: "team-1", name: "Core" },
+      },
+    ];
+    const partialRows = new Map<string, ModelRow[]>([
+      [
+        "team-2",
+        [
+          {
+            modelName: "Issue",
+            data: { id: "issue-2", title: "Team 2", teamId: "team-2" },
+          },
+        ],
+      ],
+    ]);
+    const transport = new TestTransport({
+      fullRows: rows,
+      fullMetadata: {
+        lastSyncId: 10,
+        subscribedSyncGroups: ["team-1"],
+      },
+      partialRowsByGroup: partialRows,
+    });
+
+    const client = createSyncClient({
+      storage,
+      transport,
+      reactivity: noopReactivityAdapter,
+      schema,
+    });
+
+    try {
+      await client.start();
+
+      const delta: DeltaPacket = {
+        lastSyncId: 60,
+        actions: [
+          {
+            id: 60,
+            action: "S",
+            modelName: "SyncGroup",
+            modelId: "sync-groups",
+            data: { subscribedSyncGroups: ["team-1", "team-2"] },
+          },
+        ],
+      };
+
+      const syncWaiter = waitForSync(client, 60);
+      transport.emitDelta(delta);
+      await syncWaiter;
+
+      const meta = (await storage.getMeta()) as {
+        firstSyncId?: number;
+        subscribedSyncGroups?: string[];
+      };
+      expect(meta.firstSyncId).toBe(60);
+      expect(meta.subscribedSyncGroups).toEqual(["team-1", "team-2"]);
+
+      const issueMap = client.getIdentityMap<Record<string, unknown>>("Issue");
+      expect(issueMap.get("issue-2")).toMatchObject({
+        id: "issue-2",
+        teamId: "team-2",
+      });
+
+      const partialCall = transport.bootstrapCalls.find(
+        (call) => call.type === "partial"
+      );
+      expect(partialCall?.syncGroups).toEqual(["team-2"]);
+    } finally {
+      await client.stop();
+    }
+  });
+});

package/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "paths": {}
+  },
+  "include": ["src/**/*"]
+}