@spooky-sync/core 0.0.1-canary.94 → 0.0.1-canary.96

package/dist/index.d.ts

@@ -1032,15 +1032,25 @@ interface FeatureFlagModuleDeps<S extends SchemaStructure> {
 declare class FeatureFlagModule<S extends SchemaStructure> {
   private deps;
   private logger;
-  private active;
+  private handles;
   private authUnsubscribe;
   private lastUserId;
+  private querySubscription;
+  private starting;
+  private ttl;
+  private snapshots;
+  private loaded;
   constructor(deps: FeatureFlagModuleDeps<S>);
   init(): void;
   feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle;
   closeAll(): Promise<void>;
-  private refreshAll;
-  private register;
+  /** Auth changed: drop the old user's query/snapshots and re-observe. */
+  private refresh;
+  private teardownQuery;
+  /** Start the single shared live query (idempotent; no-op with no handles). */
+  private ensureStarted;
+  /** Live query result → per-key snapshots → push to every active handle. */
+  private applyRecords;
 }
 //#endregion
 //#region src/sp00ky.d.ts

package/dist/index.js

@@ -3485,8 +3485,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.94";
-const WASM_VERSION = "0.0.1-canary.94";
+const CORE_VERSION = "0.0.1-canary.96";
+const WASM_VERSION = "0.0.1-canary.96";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -5018,7 +5018,7 @@ var CrdtManager = class {
 
 //#endregion
 //#region src/modules/feature-flag/index.ts
-const FEATURE_QUERY = "SELECT key, variant, payload FROM _00_user_feature WHERE key = $key";
+const FEATURE_QUERY = "SELECT key, variant, payload FROM _00_user_feature";
 var FeatureFlagHandle = class {
 	latest = {
 		variant: void 0,
@@ -5078,9 +5078,14 @@ var FeatureFlagHandle = class {
 };
 var FeatureFlagModule = class {
 	logger;
-	active = /* @__PURE__ */ new Set();
+	handles = /* @__PURE__ */ new Set();
 	authUnsubscribe = null;
 	lastUserId = null;
+	querySubscription = null;
+	starting = false;
+	ttl = "10m";
+	snapshots = /* @__PURE__ */ new Map();
+	loaded = false;
 	constructor(deps) {
 		this.deps = deps;
 		this.logger = deps.logger.child({ service: "FeatureFlagModule" });
@@ -5090,59 +5095,75 @@ var FeatureFlagModule = class {
 		this.authUnsubscribe = this.deps.auth.subscribe((userId) => {
 			if (userId === this.lastUserId) return;
 			this.lastUserId = userId;
-			this.refreshAll();
+			this.refresh();
 		});
 	}
 	feature(key, options = {}) {
 		const handle = new FeatureFlagHandle(key, options.fallback);
-		const entry = {
-			handle,
-			ttl: options.ttl ?? "10m"
-		};
-		this.active.add(entry);
-		handle.onClose(() => this.active.delete(entry));
-		this.register(entry);
+		this.handles.add(handle);
+		handle.onClose(() => this.handles.delete(handle));
+		if (options.ttl) this.ttl = options.ttl;
+		if (this.loaded) handle.set(this.snapshots.get(key) ?? {
+			variant: void 0,
+			payload: void 0
+		});
+		this.ensureStarted();
 		return handle;
 	}
 	async closeAll() {
 		this.authUnsubscribe?.();
 		this.authUnsubscribe = null;
-		for (const entry of [...this.active]) entry.handle.close();
-	}
-	async refreshAll() {
-		for (const entry of this.active) {
-			entry.handle.detach();
-			entry.handle.set({
-				variant: void 0,
-				payload: void 0
-			});
-			await this.register(entry);
-		}
+		this.teardownQuery();
+		for (const handle of [...this.handles]) handle.close();
+	}
+	/** Auth changed: drop the old user's query/snapshots and re-observe. */
+	async refresh() {
+		this.teardownQuery();
+		this.loaded = false;
+		this.snapshots.clear();
+		for (const handle of this.handles) handle.set({
+			variant: void 0,
+			payload: void 0
+		});
+		await this.ensureStarted();
+	}
+	teardownQuery() {
+		this.querySubscription?.();
+		this.querySubscription = null;
 	}
-	async register(entry) {
-		const { handle, ttl } = entry;
+	/** Start the single shared live query (idempotent; no-op with no handles). */
+	async ensureStarted() {
+		if (this.querySubscription || this.starting || this.handles.size === 0) return;
+		this.starting = true;
 		try {
-			const hash = await this.deps.dataModule.query("_00_user_feature", FEATURE_QUERY, { key: handle.key }, ttl);
+			const hash = await this.deps.dataModule.query("_00_user_feature", FEATURE_QUERY, {}, this.ttl);
 			this.deps.sync.enqueueDownEvent({
 				type: "register",
 				payload: { hash }
 			});
-			const unsub = this.deps.dataModule.subscribe(hash, (records) => {
-				const row = records[0];
-				handle.set({
-					variant: row?.variant,
-					payload: row?.payload
-				});
-			}, { immediate: true });
-			handle.attach(unsub);
+			this.querySubscription = this.deps.dataModule.subscribe(hash, (records) => this.applyRecords(records), { immediate: true });
 		} catch (err) {
 			this.logger.warn({
 				err,
-				key: handle.key,
 				Category: "sp00ky-client::FeatureFlagModule::register"
 			}, "Failed to register feature flag query");
+		} finally {
+			this.starting = false;
 		}
 	}
+	/** Live query result → per-key snapshots → push to every active handle. */
+	applyRecords(records) {
+		this.snapshots.clear();
+		for (const row of records ?? []) if (row && typeof row.key === "string") this.snapshots.set(row.key, {
+			variant: row.variant,
+			payload: row.payload
+		});
+		this.loaded = true;
+		for (const handle of this.handles) handle.set(this.snapshots.get(handle.key) ?? {
+			variant: void 0,
+			payload: void 0
+		});
+	}
 };
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.94",
+  "version": "0.0.1-canary.96",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,8 +59,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.94",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.94",
+    "@spooky-sync/query-builder": "0.0.1-canary.96",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.96",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",
     "loro-crdt": "^1.5.6",

package/src/modules/feature-flag/index.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { FeatureFlagModule } from './index';
+
+// Minimal mocks for the three deps the module touches. The DataModule mock
+// captures the single subscribe callback so a test can push live results, and
+// counts query() calls to assert the query is SHARED (one registration for all
+// flags), not per-key.
+function makeDeps() {
+  let subCb: ((records: unknown[]) => void) | null = null;
+  const calls: Array<{ sql: string; params: unknown }> = [];
+  let authCb: ((userId: string | null) => void) | null = null;
+
+  const dataModule = {
+    query: async (_table: string, sql: string, params: unknown) => {
+      calls.push({ sql, params });
+      return `hash:${calls.length}`;
+    },
+    subscribe: (_hash: string, cb: (records: unknown[]) => void) => {
+      subCb = cb;
+      return () => {
+        subCb = null;
+      };
+    },
+  };
+  const sync = { enqueueDownEvent: () => {} };
+  const auth = {
+    subscribe: (cb: (userId: string | null) => void) => {
+      authCb = cb;
+      return () => {
+        authCb = null;
+      };
+    },
+  };
+  const logger = { child: () => ({ warn: () => {} }) };
+
+  const deps = { dataModule, sync, auth, logger } as any;
+  return {
+    deps,
+    calls,
+    push: (records: unknown[]) => subCb?.(records),
+    setUser: (id: string | null) => authCb?.(id),
+    hasSub: () => subCb !== null,
+  };
+}
+
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+describe('FeatureFlagModule', () => {
+  let env: ReturnType<typeof makeDeps>;
+  let mod: FeatureFlagModule<any>;
+
+  beforeEach(() => {
+    env = makeDeps();
+    mod = new FeatureFlagModule(env.deps);
+  });
+
+  it('registers ONE shared, unfiltered query for many flags', async () => {
+    mod.feature('alpha');
+    mod.feature('beta');
+    mod.feature('gamma');
+    await tick();
+
+    expect(env.calls.length).toBe(1);
+    expect(env.calls[0].sql).not.toContain('WHERE');
+    expect(env.calls[0].sql).toContain('FROM _00_user_feature');
+    expect(env.calls[0].params).toEqual({});
+  });
+
+  it('fans the shared result out to each handle by key', async () => {
+    const alpha = mod.feature('alpha', { fallback: 'off' });
+    const beta = mod.feature('beta', { fallback: 'off' });
+    const missing = mod.feature('missing', { fallback: 'off' });
+    await tick();
+
+    env.push([
+      { key: 'alpha', variant: 'on' },
+      { key: 'beta', variant: 'off' },
+    ]);
+
+    expect(alpha.enabled()).toBe(true);
+    expect(alpha.variant()).toBe('on');
+    expect(beta.enabled()).toBe(false); // assigned 'off'
+    expect(missing.enabled()).toBe(false); // no row → fallback 'off'
+  });
+
+  it('observes NEW assignments live without re-registering', async () => {
+    const flag = mod.feature('live', { fallback: 'off' });
+    await tick();
+
+    env.push([]); // user starts with no assignment
+    expect(flag.enabled()).toBe(false);
+
+    env.push([{ key: 'live', variant: 'on' }]); // assigned while observing
+    expect(flag.enabled()).toBe(true);
+
+    expect(env.calls.length).toBe(1); // still the same single query
+  });
+
+  it('seeds a late-created handle from the already-loaded snapshot', async () => {
+    mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'on' }]);
+
+    const late = mod.feature('alpha', { fallback: 'off' });
+    expect(late.enabled()).toBe(true); // no fallback flash
+  });
+
+  it('clears flags and re-observes on user change', async () => {
+    mod.init();
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'on' }]);
+    expect(flag.enabled()).toBe(true);
+
+    env.setUser('user:other'); // sign-in as a different user
+    await tick();
+    expect(flag.enabled()).toBe(false); // cleared until the new query resolves
+    expect(env.hasSub()).toBe(true); // re-registered for the new user
+  });
+});

package/src/modules/feature-flag/index.ts

@@ -5,8 +5,19 @@ import type { AuthService } from '../auth/index';
 import type { Logger } from '../../services/logger/index';
 import type { QueryTimeToLive } from '../../types';
 
-const FEATURE_QUERY =
-  'SELECT key, variant, payload FROM _00_user_feature WHERE key = $key';
+// One shared LIVE query over ALL of the signed-in user's assignments — the
+// `_00_user_feature` select permission scopes it to `user = $auth.id`, so no
+// per-key `WHERE key = $key` param is needed. A single registration means every
+// flag the user is (or becomes) assigned is observed at once: new assignments
+// stream in live, and a handle for an unassigned key simply resolves to its
+// fallback. Avoids one-registration-per-flag and the param-filtered live query.
+const FEATURE_QUERY = 'SELECT key, variant, payload FROM _00_user_feature';
+
+interface FeatureRow {
+  key?: string;
+  variant?: string;
+  payload?: unknown;
+}
 
 export interface FeatureFlagSnapshot {
   variant: string | undefined;
@@ -87,17 +98,23 @@ export interface FeatureFlagModuleDeps<S extends SchemaStructure> {
   logger: Logger;
 }
 
-interface ActiveHandle {
-  handle: FeatureFlagHandle;
-  ttl: QueryTimeToLive;
-}
-
 export class FeatureFlagModule<S extends SchemaStructure> {
   private logger: Logger;
-  private active = new Set<ActiveHandle>();
+  private handles = new Set<FeatureFlagHandle>();
   private authUnsubscribe: (() => void) | null = null;
   private lastUserId: string | null = null;
 
+  // The single shared live query over the user's assignments.
+  private querySubscription: (() => void) | null = null;
+  private starting = false;
+  // Longest TTL any caller asked for (the query is shared across all flags).
+  private ttl: QueryTimeToLive = '10m';
+  // Latest assignment per key, plus whether the query has resolved at least
+  // once (so a handle created before the first result knows to wait vs. fall
+  // back). `snapshots` only holds ASSIGNED keys; an absent key → fallback.
+  private snapshots = new Map<string, FeatureFlagSnapshot>();
+  private loaded = false;
+
   constructor(private deps: FeatureFlagModuleDeps<S>) {
     this.logger = deps.logger.child({ service: 'FeatureFlagModule' });
   }
@@ -107,60 +124,86 @@ export class FeatureFlagModule<S extends SchemaStructure> {
     this.authUnsubscribe = this.deps.auth.subscribe((userId) => {
       if (userId === this.lastUserId) return;
       this.lastUserId = userId;
-      void this.refreshAll();
+      void this.refresh();
     });
   }
 
   feature(key: string, options: FeatureFlagOptions = {}): FeatureFlagHandle {
     const handle = new FeatureFlagHandle(key, options.fallback);
-    const entry: ActiveHandle = { handle, ttl: options.ttl ?? '10m' };
-    this.active.add(entry);
-    handle.onClose(() => this.active.delete(entry));
-    void this.register(entry);
+    this.handles.add(handle);
+    handle.onClose(() => this.handles.delete(handle));
+    if (options.ttl) this.ttl = options.ttl;
+    // If the shared query already resolved, seed this handle immediately so a
+    // late `feature()` call doesn't flash the fallback for an assigned key.
+    if (this.loaded) {
+      handle.set(this.snapshots.get(key) ?? { variant: undefined, payload: undefined });
+    }
+    void this.ensureStarted();
     return handle;
   }
 
   async closeAll(): Promise<void> {
     this.authUnsubscribe?.();
     this.authUnsubscribe = null;
-    for (const entry of [...this.active]) entry.handle.close();
+    this.teardownQuery();
+    for (const handle of [...this.handles]) handle.close();
   }
 
-  private async refreshAll(): Promise<void> {
-    for (const entry of this.active) {
-      entry.handle.detach();
-      entry.handle.set({ variant: undefined, payload: undefined });
-      await this.register(entry);
+  /** Auth changed: drop the old user's query/snapshots and re-observe. */
+  private async refresh(): Promise<void> {
+    this.teardownQuery();
+    this.loaded = false;
+    this.snapshots.clear();
+    // Clear handles immediately so a sign-out hides flag-gated UI without lag.
+    for (const handle of this.handles) {
+      handle.set({ variant: undefined, payload: undefined });
     }
+    await this.ensureStarted();
+  }
+
+  private teardownQuery(): void {
+    this.querySubscription?.();
+    this.querySubscription = null;
   }
 
-  private async register(entry: ActiveHandle): Promise<void> {
-    const { handle, ttl } = entry;
+  /** Start the single shared live query (idempotent; no-op with no handles). */
+  private async ensureStarted(): Promise<void> {
+    if (this.querySubscription || this.starting || this.handles.size === 0) return;
+    this.starting = true;
     try {
       const hash = await this.deps.dataModule.query(
         '_00_user_feature' as any,
         FEATURE_QUERY,
-        { key: handle.key },
-        ttl,
+        {},
+        this.ttl,
       );
-
       this.deps.sync.enqueueDownEvent({ type: 'register', payload: { hash } });
-
-      const unsub = this.deps.dataModule.subscribe(
+      this.querySubscription = this.deps.dataModule.subscribe(
         hash,
-        (records) => {
-          const row = records[0] as { variant?: string; payload?: unknown } | undefined;
-          handle.set({ variant: row?.variant, payload: row?.payload });
-        },
+        (records) => this.applyRecords(records as FeatureRow[]),
         { immediate: true },
       );
-
-      handle.attach(unsub);
     } catch (err) {
       this.logger.warn(
-        { err, key: handle.key, Category: 'sp00ky-client::FeatureFlagModule::register' },
+        { err, Category: 'sp00ky-client::FeatureFlagModule::register' },
         'Failed to register feature flag query',
       );
+    } finally {
+      this.starting = false;
+    }
+  }
+
+  /** Live query result → per-key snapshots → push to every active handle. */
+  private applyRecords(records: FeatureRow[]): void {
+    this.snapshots.clear();
+    for (const row of records ?? []) {
+      if (row && typeof row.key === 'string') {
+        this.snapshots.set(row.key, { variant: row.variant, payload: row.payload });
+      }
+    }
+    this.loaded = true;
+    for (const handle of this.handles) {
+      handle.set(this.snapshots.get(handle.key) ?? { variant: undefined, payload: undefined });
     }
   }
 }