@strata-sync/client 0.1.0

package/AGENTS.md

@@ -0,0 +1,24 @@
+# @strata-sync/client
+
+Client orchestration, outbox management, delta processing, and query execution.
+
+## Commands
+
+- `npm run build` — compile TypeScript (`tsc -p tsconfig.build.json`)
+- `npm run dev` — watch mode (`tsc --watch -p tsconfig.build.json`)
+- `npm run test` — run tests (`vitest run`)
+- `npm run lint` — lint with Biome
+- `npm run check-types` — type check without emitting
+
+## Gotchas
+
+- Uses `tsconfig.build.json` for builds (not the default `tsconfig.json`) — the build config excludes test files
+- Depends on both `@strata-sync/core` and `@strata-sync/yjs` — both must be built first
+- The outbox batches mutations for offline-first support — mutations are not sent immediately when offline
+- Identity map deduplicates model instances — never create model instances outside the identity map
+
+## Conventions
+
+- SyncClient is the single orchestrator — all sync lifecycle goes through it
+- Queries use predicate functions for filtering (`where: (item) => boolean`)
+- Outbox entries are ordered and must be replayed in sequence on reconnect

package/README.md

@@ -0,0 +1,63 @@
+# @strata-sync/client
+
+Client orchestration, outbox management, delta processing, and query execution for the Strata Sync.
+
+## Overview
+
+sync-client coordinates the client-side sync lifecycle:
+
+- **SyncClient** — main orchestrator for the sync lifecycle
+- **Outbox manager** — batches mutations for offline-first support
+- **Identity map** — canonical in-memory object instances (deduplication)
+- **Query execution** — filtering, lazy loading, and predicate-based queries
+- **Connection state** — manages online/offline/syncing states
+
+## Installation
+
+```bash
+npm install @strata-sync/client
+```
+
+Dependencies: `@strata-sync/core`, `@strata-sync/yjs`
+
+## Usage
+
+```typescript
+import { SyncClient } from "@strata-sync/client";
+
+const client = new SyncClient({ /* config */ });
+
+// Create (optimistic by default)
+await client.create("Issue", {
+  id: crypto.randomUUID(),
+  title: "New issue",
+  workspaceId,
+  createdAt: Date.now(),
+});
+
+// Update
+await client.update("Issue", issueId, {
+  title: "Updated title",
+});
+
+// Delete
+await client.delete("Issue", issueId);
+
+// Query
+const issues = client.query("Issue", {
+  where: (i) => i.workspaceId === workspaceId,
+  limit: 50,
+});
+```
+
+## Package Structure
+
+```
+src/
+├── client.ts           — Main SyncClient class
+├── sync-orchestrator.ts — Lifecycle management
+├── outbox-manager.ts   — Mutation batching for offline-first
+├── identity-map.ts     — Object deduplication
+├── query.ts            — Query execution engine
+└── types.ts            — Shared type definitions
+```

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@strata-sync/client",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch -p tsconfig.build.json",
+    "lint": "biome lint .",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@strata-sync/core": "*",
+    "@strata-sync/yjs": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@biomejs/biome": "^2.3.12",
+    "vitest": "^4.0.18"
+  }
+}