@laboverwire/stitch 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 ## Unreleased
 
+### Added
+
+- _Nothing yet._
+
+## 0.5.0
+
+### Changed (breaking)
+
+- **Store backend replaced by `@laboverwire/stitch-wasm`.** The entire TypeScript store — memory cache, IndexedDB persistence, MQTT sync, offline queue — has been removed. `@laboverwire/stitch` is now a thin, framework-agnostic binding layer: `src/store.ts` is a small adapter that wraps the Rust/WASM `Store` from `@laboverwire/stitch-wasm` (`^0.2.1`), and the package ships the same React and Vue bindings. All store/sync/persistence/offline-queue/MQTT logic now lives inside the wasm (compiled from the sibling `stitch-rs` repo).
+- **`StoreOptions.remote` shape changed.** `remote` is now `{ url, clientId?, ticket?, username?, password? }` instead of `{ serverUrl, getTicket }`. `url` is a `ws://`|`wss://` MQTT endpoint; `ticket` is a JWT for MQTT v5 enhanced auth; `username`/`password` drive classic MQTT password auth. `persistence` is `{ dbName, passphrase? }` — supplying `passphrase` enables AES-GCM encryption.
+- **`responseTopicPrefix` default moved off `$SYS`.** Default changed from `$SYS/responses` to `$DB/clients`. The previous default published responses under `$SYS`, which the MQTT 5 spec reserves for broker-internal use (§4.7.2) — production brokers (EMQX, HiveMQ, AWS IoT Core) reject client publishes under `$SYS` by default ACL, so the old default only worked against permissive or custom-configured brokers. Per-request response topic shape is unchanged: `{prefix}/{clientId}/{requestId}`. The `responseTopicPrefix` config field still exists on `StoreConfig` and is forwarded to the wasm; only the implementation moved. Deployments overriding `responseTopicPrefix` explicitly are unaffected. Deployments relying on the old default must either set `responseTopicPrefix: '$SYS/responses'` to preserve current behavior or update broker ACLs to accept the new `$DB/clients/...` topic.
+- **Subscription callbacks are now asynchronous.** `subscribeToEntity` and `subscribeToScope` callbacks fire one tick after the mutating call resolves, not synchronously within it. Callers that relied on synchronous delivery must not assume the callback has run by the time `create`/`update`/`delete` returns.
+- **`connectionStatus` values are lowercase** — `'connected' | 'connecting' | 'disconnected' | 'error' | 'offline'`.
+
+### Added
+
+- **`@laboverwire/stitch-wasm` dependency** (`^0.2.1`) — the Rust/WASM store, MQTT client, and IndexedDB persistence, bundled as a single wasm-bindgen module.
+- **Pre-initialize tolerance in the adapter.** The wasm store requires `initialize()` before use, but the TS adapter tolerates pre-init access: synchronous reads return empties (`[]` / `{}` / `null` / `0` / `'offline'`) before init, `subscribe*` defer wiring until `initialize()` resolves and then trigger a re-read, and async methods await init. React and Vue hooks are therefore safe to mount before the provider finishes initializing.
+- **`Store.getVersion(scopeId, entity): number`** — reactivity token used by the memory snapshot cache.
+- **`Store.pendingMutationCount(scopeId): Promise<number>`** — offline-queue depth for a scope.
+
+### Removed
+
+- **In-package store internals.** `src/memory-store.ts`, `src/persistence-layer.ts`, `src/remote-sync-layer.ts`, `src/sync-engine.ts`, `src/offline-queue.ts`, `src/internal-utils.ts`, and `src/internal-wasm-error.ts` deleted — their logic now lives in `@laboverwire/stitch-wasm`.
+- **`mqdb-wasm` and `mqtt5-wasm` direct dependencies.** Both are now bundled inside `@laboverwire/stitch-wasm`.
+- **Internal factory exports.** `createMemoryStore`, `createSyncEngine`, `createPersistenceLayer`, `createRemoteSyncLayer`, `createPersistentOfflineQueue`, `createInMemoryOfflineQueue` removed. The only value export is now `createStore`.
+- **`OwnershipError` and `MqdbError` classes** removed — error handling for the wasm store no longer surfaces these TS types.
+- **Session/auth-cache `Store` methods removed.** `getCachedUser`, `setCachedUser`, `clearCachedUser`, `hasPendingLogout`, `setPendingLogout`, and `flushPendingLogout` are no longer on `Store`. They were thin `sessionStorage` wrappers; apps that relied on them must reimplement the caching in application code.
+- **Internal-layer interface types.** `SyncEngine`, `PersistenceLayer`, `RemoteSyncLayer`, `OfflineQueue`, `MutationSender`, `LocalAccessor`, `PendingMutation`, `ConsolidatedMutation`, `ScopeBundle`, `ScopeState`, `SyncMutation`, `MutationEvent` no longer exported. The public type surface is now `StoreConfig`, `EntityDefinition`, `SchemaField`, `ForeignKeyDefinition`, `ConnectionStatus`, `SortField`, `SortDirection`, `ListFilter`, `Store`, `StoreOptions`, `PersistenceConfig`, `RemoteConfig`, `MemoryStore`, `EntitySchema`, `DefaultSchema`, `EntityKey`, and `OriginTag`. The `MemoryStore` type still exists but is trimmed to `{ getSnapshot, getSnapshotAsMap, subscribeToScope }`.
+- **Consumer Vite `server.fs.allow` / `optimizeDeps.exclude` guidance obsolete.** `stitch-wasm` ships a wasm-bindgen bundler-target ESM module (ESM wasm import proposal), so a consuming Vite app must instead add `vite-plugin-wasm` and `vite-plugin-top-level-await`, and set `build.target: 'esnext'` for production builds (the wasm module and the top-level-await plugin emit top-level `await`). The old `mqdb-wasm`/`mqtt5-wasm` filesystem-allow and dep-exclude instructions no longer apply and must be removed. This repo's `vitest.config.ts` now uses those two plugins and the browser test suite loads the real wasm.
+
+### Fixed
+
+- **React/Vue init-order safety.** Because the adapter tolerates pre-init access (see Added), hooks like `useEntitySnapshot`, `useScopedEntities`, and `useRootEntityList` no longer read stale or throwing state when a component mounts before the provider's `initialize()` resolves — `subscribe*` wires up and re-reads once init completes.
+- **Brittle response-topic parsing** now lives in `@laboverwire/stitch-wasm`. The former `src/sync-engine.ts` regex that split `{prefix}/{clientId}/{requestId}` on a fixed segment count is gone along with the file; the wasm handles response-topic matching against the configured `responseTopicPrefix`.
+
+### Unchanged
+
+- **React bindings** — `StoreProvider`, `AuthProvider`, `useEntitySnapshot`, `useScopedEntities`, `useRootEntityList`, `useTopLevelEntities`, `useChildCounts`, `useConnectionStatus`, `useSyncScope`, `useStore` — and **Vue bindings** — `StoreRoot`, `StitchAuth`, matching composables, and `useStore` — keep the same API. `Store.reconnect(serverUrl, getTicket?)` also keeps its signature: the adapter resolves the ticket via `getTicket` and runs any reconnect validator.
+
 ## 0.4.3
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # @laboverwire/stitch
 
-Reactive state synchronization library. Bridges an in-memory store, IndexedDB persistence, and MQTT-based remote sync into a single `Store` interface. Optional React and Vue 3 bindings.
+Reactive state synchronization for React and Vue. A thin, framework-agnostic binding layer over [`@laboverwire/stitch-wasm`](https://www.npmjs.com/package/@laboverwire/stitch-wasm) — a Rust/WASM package that owns the in-memory store, IndexedDB persistence, and MQTT-based remote sync. This package wraps that WASM `Store` in a small adapter and ships React and Vue 3 bindings on top; all store, sync, persistence, and offline-queue logic lives inside the WASM.
 
 ```bash
 npm install @laboverwire/stitch
@@ -11,7 +11,7 @@ import { createStore } from '@laboverwire/stitch';
 
 const store = createStore<Schema>(config, {
   persistence: { dbName: 'my-app' },
-  remote: { serverUrl: 'wss://mqtt.example.com', getTicket: () => fetchAuthTicket() },
+  remote: { url: 'wss://mqtt.example.com', ticket: await fetchAuthTicket() },
 });
 
 await store.initialize();
@@ -20,15 +20,18 @@ await store.replaceScope('project-abc');
 const tasks = store.getSnapshot('task', 'project-abc');
 ```
 
+`remote.url` is a `ws://`/`wss://` MQTT endpoint. Pass `ticket` (a JWT) for MQTT v5 enhanced auth, or `username`/`password` for classic password auth. A `persistence.passphrase` enables AES-GCM encryption of the IndexedDB store.
+
 ## Documentation
 
 - [Configuration](./docs/configuration.md) — `StoreConfig`, `StoreOptions`, scope model, typed schemas
-- [Store API](./docs/api.md) — full method reference and error handling
+- [Store API](./docs/api.md) — full method reference
 - [React bindings](./docs/react.md) — providers, hooks, runnable example
 - [Vue 3 bindings](./docs/vue.md) — providers, composables, runnable example
 - [Concepts](./docs/concepts.md) — origin tags, offline queue, reconciliation, connection resilience
-- [Vite consumer guide](./docs/vite-consumer.md) — using the package via source alias from a monorepo
-- [Architecture](./ARCHITECTURE.md) — internal layer composition, data flow, invariants
+- [Vite consumer guide](./docs/vite-consumer.md) — consuming apps must add `vite-plugin-wasm` (and `vite-plugin-top-level-await`) so the bundler can load the WASM module
+- [Architecture](./ARCHITECTURE.md) — layer composition, data flow, invariants
+- [Upgrading to 0.5.0](./docs/upgrading-to-0.5.md) — breaking changes and step-by-step upgrade from 0.4.x
 - [Changelog](./CHANGELOG.md)
 - [Releasing](./RELEASING.md)
 

package/dist/index.d.ts

@@ -1,10 +1,3 @@
-export type { StoreConfig, EntityDefinition, SchemaField, ForeignKeyDefinition, MutationEvent, ScopeBundle, ScopeState, ConnectionStatus, SortField, SortDirection, ListFilter, SyncMutation, MemoryStore, SyncEngine, Store, StoreOptions, PersistenceConfig, RemoteConfig, PersistenceLayer, OfflineQueue, RemoteSyncLayer, LocalAccessor, MutationSender, PendingMutation, ConsolidatedMutation, EntitySchema, DefaultSchema, EntityKey, OriginTag, } from './types.ts';
-export { OwnershipError } from './types.ts';
-export { MqdbError } from './internal-wasm-error.ts';
-export { createMemoryStore } from './memory-store.ts';
-export { createSyncEngine } from './sync-engine.ts';
+export type { StoreConfig, EntityDefinition, SchemaField, ForeignKeyDefinition, ConnectionStatus, SortField, SortDirection, ListFilter, Store, StoreOptions, PersistenceConfig, RemoteConfig, MemoryStore, EntitySchema, DefaultSchema, EntityKey, OriginTag, } from './types.ts';
 export { createStore } from './store.ts';
-export { createPersistenceLayer } from './persistence-layer.ts';
-export { createRemoteSyncLayer } from './remote-sync-layer.ts';
-export { createPersistentOfflineQueue, createInMemoryOfflineQueue } from './offline-queue.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,UAAU,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,KAAK,EACL,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACb,SAAS,EACT,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAErD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,oBAAoB,EACpB,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,UAAU,EACV,KAAK,EACL,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,aAAa,EACb,SAAS,EACT,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,9 +1,2 @@
-export { OwnershipError } from "./types.js";
-export { MqdbError } from "./internal-wasm-error.js";
-export { createMemoryStore } from "./memory-store.js";
-export { createSyncEngine } from "./sync-engine.js";
 export { createStore } from "./store.js";
-export { createPersistenceLayer } from "./persistence-layer.js";
-export { createRemoteSyncLayer } from "./remote-sync-layer.js";
-export { createPersistentOfflineQueue, createInMemoryOfflineQueue } from "./offline-queue.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAErD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC","sourcesContent":["export type {\n  StoreConfig,\n  EntityDefinition,\n  SchemaField,\n  ForeignKeyDefinition,\n  MutationEvent,\n  ScopeBundle,\n  ScopeState,\n  ConnectionStatus,\n  SortField,\n  SortDirection,\n  ListFilter,\n  SyncMutation,\n  MemoryStore,\n  SyncEngine,\n  Store,\n  StoreOptions,\n  PersistenceConfig,\n  RemoteConfig,\n  PersistenceLayer,\n  OfflineQueue,\n  RemoteSyncLayer,\n  LocalAccessor,\n  MutationSender,\n  PendingMutation,\n  ConsolidatedMutation,\n  EntitySchema,\n  DefaultSchema,\n  EntityKey,\n  OriginTag,\n} from './types.ts';\n\nexport { OwnershipError } from './types.ts';\nexport { MqdbError } from './internal-wasm-error.ts';\n\nexport { createMemoryStore } from './memory-store.ts';\nexport { createSyncEngine } from './sync-engine.ts';\nexport { createStore } from './store.ts';\nexport { createPersistenceLayer } from './persistence-layer.ts';\nexport { createRemoteSyncLayer } from './remote-sync-layer.ts';\nexport { createPersistentOfflineQueue, createInMemoryOfflineQueue } from './offline-queue.ts';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC","sourcesContent":["export type {\n  StoreConfig,\n  EntityDefinition,\n  SchemaField,\n  ForeignKeyDefinition,\n  ConnectionStatus,\n  SortField,\n  SortDirection,\n  ListFilter,\n  Store,\n  StoreOptions,\n  PersistenceConfig,\n  RemoteConfig,\n  MemoryStore,\n  EntitySchema,\n  DefaultSchema,\n  EntityKey,\n  OriginTag,\n} from './types.ts';\n\nexport { createStore } from './store.ts';\n"]}

package/dist/react/provider.d.ts

@@ -12,7 +12,7 @@ interface StoreProviderProps {
  * handlers, logout gating) live in {@link AuthProvider}; compose both if you need
  * an auth-aware app.
  */
-export declare function StoreProvider({ store, serverUrl, getTicket, children }: StoreProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function StoreProvider({ store, serverUrl, getTicket, children }: StoreProviderProps): import("react").JSX.Element;
 interface AuthProviderProps {
     store: Store;
     userId?: string;
@@ -27,6 +27,6 @@ interface AuthProviderProps {
  * Controls `setAuthenticatedUser`, session-invalid + reconnect-validator handlers, and
  * tears down the store via `resetForLogout()` when `authenticated` transitions to false.
  */
-export declare function AuthProvider({ store, userId, authenticated, onSessionInvalid, onReconnectValidate, children, }: AuthProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function AuthProvider({ store, userId, authenticated, onSessionInvalid, onReconnectValidate, children, }: AuthProviderProps): import("react").JSX.Element;
 export {};
 //# sourceMappingURL=provider.d.ts.map

package/dist/react/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/react/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACrE,OAAO,KAAK,EAAoB,KAAK,EAAE,MAAM,aAAa,CAAC;AAG3D,UAAU,kBAAkB;IAC1B,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,kBAAkB,2CA8E1F;AAED,UAAU,iBAAiB;IACzB,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iHAAiH;IACjH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,MAAM,EACN,aAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,QAAQ,GACT,EAAE,iBAAiB,2CAanB"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/react/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACrE,OAAO,KAAK,EAAoB,KAAK,EAAE,MAAM,aAAa,CAAC;AAG3D,UAAU,kBAAkB;IAC1B,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,kBAAkB,+BA8E1F;AAED,UAAU,iBAAiB;IACzB,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iHAAiH;IACjH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,MAAM,EACN,aAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,QAAQ,GACT,EAAE,iBAAiB,+BAanB"}

package/dist/store.d.ts

@@ -1,3 +1,3 @@
-import type { StoreConfig, StoreOptions, Store } from './types.ts';
-export declare function createStore<S extends import('./types.ts').EntitySchema = import('./types.ts').DefaultSchema>(config: StoreConfig, options?: StoreOptions): Store<S>;
+import type { DefaultSchema, EntitySchema, Store, StoreConfig, StoreOptions } from './types.ts';
+export declare function createStore<S extends EntitySchema = DefaultSchema>(config: StoreConfig, options?: StoreOptions): Store<S>;
 //# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,KAAK,EAYN,MAAM,YAAY,CAAC;AA82BpB,wBAAgB,WAAW,CACzB,CAAC,SAAS,OAAO,YAAY,EAAE,YAAY,GAAG,OAAO,YAAY,EAAE,aAAa,EAChF,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAEvD"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,aAAa,EAEb,YAAY,EAKZ,KAAK,EACL,WAAW,EACX,YAAY,EACb,MAAM,YAAY,CAAC;AAuUpB,wBAAgB,WAAW,CAAC,CAAC,SAAS,YAAY,GAAG,aAAa,EAChE,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,YAAY,GACrB,KAAK,CAAC,CAAC,CAAC,CAIV"}