@spooky-sync/client-solid 0.0.1-canary.9 → 0.0.1-canary.91

package/src/index.ts

@@ -1,14 +1,15 @@
 import type { SyncedDbConfig } from './types';
 import {
-  SpookyClient,
-  AuthService,
-  BucketHandle,
-  type SpookyQueryResultPromise,
-  UpdateOptions,
-  RunOptions,
+  Sp00kyClient,
+  type Sp00kyQueryResultPromise,
+  type AuthService,
+  type BucketHandle,
+  type UpdateOptions,
+  type RunOptions,
+  type SyncHealth,
 } from '@spooky-sync/core';
 
-import {
+import type {
   GetTable,
   QueryBuilder,
   SchemaStructure,
@@ -25,19 +26,30 @@ import {
   RoutePayload,
   BucketNames,
   BucketDefinitionSchema,
+  QueryModifier,
+  QueryModifierBuilder,
+  QueryInfo,
+  RelationshipsMetadata,
+  RelationshipDefinition,
+  InferRelatedModelFromMetadata,
+  GetCardinality,
 } from '@spooky-sync/query-builder';
 
-import { RecordId, Uuid, Surreal } from 'surrealdb';
+import { RecordId, Uuid, type Surreal } from 'surrealdb';
 export { RecordId, Uuid };
 export type { Model, GenericModel, GenericSchema, ModelPayload } from './lib/models';
 export { useQuery } from './lib/use-query';
+export { useSyncStatus, type UseSyncStatus } from './lib/use-sync-status';
+export type { SyncHealth, SyncHealthStatus, SyncHealthConfig } from '@spooky-sync/core';
+export { useCrdtField } from './lib/use-crdt-field';
+export { useFeatureFlag, type UseFeatureFlag } from './lib/use-feature-flag';
 export { useFileUpload, type FileUploadResult } from './lib/use-file-upload';
 export { useDownloadFile, type UseDownloadFileOptions, type UseDownloadFileResult } from './lib/use-download-file';
-export { SpookyProvider, type SpookyProviderProps } from './lib/SpookyProvider';
+export { Sp00kyProvider, type Sp00kyProviderProps } from './lib/Sp00kyProvider';
 export { useDb } from './lib/context';
 
 // export { AuthEventTypes } from "@spooky-sync/core"; // TODO: Verify if AuthEventTypes exists in core
-export type {};
+
 
 // Re-export query builder types for convenience
 export type {
@@ -52,7 +64,7 @@ export type {
   TableModel,
   TableNames,
   QueryResult,
-} from '@spooky-sync/query-builder';
+};
 
 export type RelationshipField<
   Schema extends SchemaStructure,
@@ -94,30 +106,30 @@ export type WithRelatedMany<Field extends string, RelatedFields extends RelatedF
 };
 
 /**
- * SyncedDb - A thin wrapper around spooky-ts for Solid.js integration
- * Delegates all logic to the underlying spooky-ts instance
+ * SyncedDb - A thin wrapper around sp00ky-ts for Solid.js integration
+ * Delegates all logic to the underlying sp00ky-ts instance
  */
 export class SyncedDb<S extends SchemaStructure> {
   private config: SyncedDbConfig<S>;
-  private spooky: SpookyClient<S> | null = null;
+  private sp00ky: Sp00kyClient<S> | null = null;
   private _initialized = false;
 
   constructor(config: SyncedDbConfig<S>) {
     this.config = config;
   }
 
-  public getSpooky(): SpookyClient<S> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky;
+  public getSp00ky(): Sp00kyClient<S> {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky;
   }
 
   /**
-   * Initialize the spooky-ts instance
+   * Initialize the sp00ky-ts instance
    */
   async init(): Promise<void> {
     if (this._initialized) return;
-    this.spooky = new SpookyClient<S>(this.config);
-    await this.spooky.init();
+    this.sp00ky = new Sp00kyClient<S>(this.config);
+    await this.sp00ky.init();
     this._initialized = true;
   }
 
@@ -125,8 +137,8 @@ export class SyncedDb<S extends SchemaStructure> {
    * Create a new record in the database
    */
   async create(id: string, payload: Record<string, unknown>): Promise<void> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    await this.spooky.create(id, payload as Record<string, unknown>);
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    await this.sp00ky.create(id, payload as Record<string, unknown>);
   }
 
   /**
@@ -138,8 +150,8 @@ export class SyncedDb<S extends SchemaStructure> {
     payload: Partial<TableModel<GetTable<S, TName>>>,
     options?: UpdateOptions
   ): Promise<void> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    await this.spooky.update(
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    await this.sp00ky.update(
       tableName as string,
       recordId,
       payload as Record<string, unknown>,
@@ -152,12 +164,26 @@ export class SyncedDb<S extends SchemaStructure> {
    */
   async delete<TName extends TableNames<S>>(
     tableName: TName,
-    selector: string | InnerQuery<GetTable<S, TName>, boolean>
+    selector: string | RecordId | InnerQuery<GetTable<S, TName>, boolean>
   ): Promise<void> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    if (typeof selector !== 'string')
-      throw new Error('Only string ID selectors are supported currently with core');
-    await this.spooky.delete(tableName as string, selector);
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    // Accept a `"table:id"` string OR a RecordId — live-query rows carry their
+    // `id` as a RecordId, so callers can pass `db.delete('game', row.id)`
+    // directly. Build the canonical string from the raw id part (not
+    // `RecordId.toString()`, which escapes special chars) so it round-trips
+    // through the engine's `parseRecordIdString`. InnerQuery selectors are not
+    // supported yet. (cross-package RecordId instances → match by constructor name.)
+    const isRecordId =
+      selector instanceof RecordId || (selector as any)?.constructor?.name === 'RecordId';
+    let id: string;
+    if (typeof selector === 'string') {
+      id = selector;
+    } else if (isRecordId) {
+      id = `${tableName as string}:${(selector as RecordId).id}`;
+    } else {
+      throw new Error('Only string ID or RecordId selectors are supported currently with core');
+    }
+    await this.sp00ky.delete(tableName as string, id);
   }
 
   /**
@@ -165,9 +191,9 @@ export class SyncedDb<S extends SchemaStructure> {
    */
   public query<TName extends TableNames<S>>(
     table: TName
-  ): QueryBuilder<S, TName, SpookyQueryResultPromise, {}, false> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky.query(table, {});
+  ): QueryBuilder<S, TName, Sp00kyQueryResultPromise, {}, false> {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.query(table, {});
   }
 
   /**
@@ -182,17 +208,17 @@ export class SyncedDb<S extends SchemaStructure> {
     payload: RoutePayload<S, B, R>,
     options?: RunOptions,
   ): Promise<void> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    await this.spooky.run(backend, path, payload, options);
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    await this.sp00ky.run(backend, path, payload, options);
   }
 
   /**
    * Authenticate with the database
    */
   public async authenticate(token: string): Promise<RecordId<string>> {
-    const result = await this.spooky?.authenticate(token);
-    // SpookyClient.authenticate returns whatever remote.authenticate returns (boolean or token usually?)
-    // Wait, checked SpookyClient: return this.remote.getClient().authenticate(token);
+    await this.sp00ky?.authenticate(token);
+    // Sp00kyClient.authenticate returns whatever remote.authenticate returns (boolean or token usually?)
+    // Wait, checked Sp00kyClient: return this.remote.getClient().authenticate(token);
     // SurrealDB authenticate returns void? or token?
     // Assuming void or token.
     return new RecordId('user', 'me'); // Placeholder or actual?
@@ -210,54 +236,76 @@ export class SyncedDb<S extends SchemaStructure> {
    * Sign out, clear session and local storage
    */
   public async signOut(): Promise<void> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    await this.spooky.auth.signOut();
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    await this.sp00ky.auth.signOut();
   }
 
   /**
    * Execute a function with direct access to the remote database connection
    */
   public async useRemote<T>(fn: (db: Surreal) => T | Promise<T>): Promise<T> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return await this.spooky.useRemote(fn);
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return await this.sp00ky.useRemote(fn);
   }
   /**
    * Access the remote database service directly
    */
-  get remote(): SpookyClient<S>['remoteClient'] {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky.remoteClient;
+  get remote(): Sp00kyClient<S>['remoteClient'] {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.remoteClient;
   }
 
   /**
    * Access the local database service directly
    */
-  get local(): SpookyClient<S>['localClient'] {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky.localClient;
+  get local(): Sp00kyClient<S>['localClient'] {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.localClient;
   }
 
   /**
    * Access the auth service
    */
   get auth(): AuthService<S> {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky.auth;
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.auth;
   }
 
   get pendingMutationCount(): number {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky.pendingMutationCount;
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.pendingMutationCount;
+  }
+
+  /** Diagnostic — see `Sp00kyClient.liveRetryCount`. */
+  get liveRetryCount(): number {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.liveRetryCount;
   }
 
   subscribeToPendingMutations(cb: (count: number) => void): () => void {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky.subscribeToPendingMutations(cb);
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.subscribeToPendingMutations(cb);
+  }
+
+  /** Current sync-health snapshot. See {@link useSyncStatus}. */
+  get syncHealth(): SyncHealth {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.syncHealth;
+  }
+
+  /**
+   * Observe sync health. Fires immediately with the current status and again
+   * on every healthy↔degraded transition. Prefer the `useSyncStatus` hook in
+   * components; this is the imperative escape hatch.
+   */
+  subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.subscribeToSyncHealth(cb);
   }
 
   bucket<B extends BucketNames<S>>(name: B): BucketHandle {
-    if (!this.spooky) throw new Error('SyncedDb not initialized');
-    return this.spooky.bucket(name);
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.bucket(name);
   }
 
   getBucketConfig(name: string): BucketDefinitionSchema | undefined {

package/src/lib/{SpookyProvider.ts → Sp00kyProvider.ts}

@@ -1,10 +1,11 @@
-import { createSignal, onMount, createComponent, createMemo, JSX, mergeProps } from 'solid-js';
+import type { JSX} from 'solid-js';
+import { createSignal, onMount, createComponent, createMemo, mergeProps } from 'solid-js';
 import type { SchemaStructure } from '@spooky/query-builder';
 import type { SyncedDbConfig } from '../types';
 import { SyncedDb } from '../index';
-import { SpookyContext } from './context';
+import { Sp00kyContext } from './context';
 
-export interface SpookyProviderProps<S extends SchemaStructure> {
+export interface Sp00kyProviderProps<S extends SchemaStructure> {
   config: SyncedDbConfig<S>;
   fallback?: JSX.Element;
   onError?: (error: Error) => void;
@@ -12,8 +13,8 @@ export interface SpookyProviderProps<S extends SchemaStructure> {
   children: JSX.Element;
 }
 
-export function SpookyProvider<S extends SchemaStructure>(
-  props: SpookyProviderProps<S>
+export function Sp00kyProvider<S extends SchemaStructure>(
+  props: Sp00kyProviderProps<S>
 ): JSX.Element {
   const merged = mergeProps(
     {
@@ -35,7 +36,8 @@ export function SpookyProvider<S extends SchemaStructure>(
       if (merged.onError) {
         merged.onError(error);
       } else {
-        console.error('SpookyProvider: Failed to initialize database', error);
+        // oxlint-disable-next-line no-console
+        console.error('Sp00kyProvider: Failed to initialize database', error);
       }
     }
   });
@@ -43,7 +45,7 @@ export function SpookyProvider<S extends SchemaStructure>(
   const content = createMemo(() => {
     const instance = db();
     if (!instance) return merged.fallback;
-    return createComponent(SpookyContext.Provider, {
+    return createComponent(Sp00kyContext.Provider, {
       value: instance,
       get children() {
         return merged.children;

package/src/lib/context.ts

@@ -2,12 +2,12 @@ import { createContext, useContext } from 'solid-js';
 import type { SchemaStructure } from '@spooky/query-builder';
 import type { SyncedDb } from '../index';
 
-export const SpookyContext = createContext<SyncedDb<any> | undefined>();
+export const Sp00kyContext = createContext<SyncedDb<any> | undefined>();
 
 export function useDb<S extends SchemaStructure>(): SyncedDb<S> {
-  const db = useContext(SpookyContext);
+  const db = useContext(Sp00kyContext);
   if (!db) {
-    throw new Error('useDb must be used within a <SpookyProvider>. Wrap your app in <SpookyProvider config={...}>.');
+    throw new Error('useDb must be used within a <Sp00kyProvider>. Wrap your app in <Sp00kyProvider config={...}>.');
   }
   return db as SyncedDb<S>;
 }

package/src/lib/models.ts

@@ -1,4 +1,4 @@
-import { RecordId } from 'surrealdb';
+import type { RecordId } from 'surrealdb';
 
 // Re-export types from query-builder for backward compatibility
 export type { GenericModel, GenericSchema } from '@spooky/query-builder';

package/src/lib/use-crdt-field.ts

@@ -0,0 +1,68 @@
+import { createEffect, createSignal, onCleanup, useContext, type Accessor } from 'solid-js';
+import { Sp00kyContext } from './context';
+import type { CrdtField } from '@spooky-sync/core';
+
+export function useCrdtField(
+  table: string,
+  recordId: () => string | undefined,
+  field: string,
+  fallbackText?: () => string | undefined,
+): Accessor<CrdtField | null> {
+  const db = useContext(Sp00kyContext);
+  if (!db) {
+    throw new Error('useCrdtField must be used within a <Sp00kyProvider>');
+  }
+
+  const [crdtField, setCrdtField] = createSignal<CrdtField | null>(null);
+  let currentId: string | undefined;
+  let initialized = false;
+
+  createEffect(() => {
+    const id = recordId();
+
+    // Skip if the ID hasn't changed (but allow the first non-undefined value through)
+    if (initialized && id === currentId) return;
+
+    // Close previous field
+    if (currentId && crdtField()) {
+      db.getSp00ky().closeCrdtField(table, currentId, field);
+      setCrdtField(null);
+    }
+
+    currentId = id;
+    initialized = true;
+
+    if (!id) return;
+
+    const sp00ky = db.getSp00ky();
+    const text = fallbackText?.();
+    sp00ky
+      .openCrdtField(table, id, field, text)
+      .then((cf) => {
+        if (currentId === id) {
+          setCrdtField(cf);
+        }
+      })
+      .catch((err) => {
+        // Silent rejections here leave the consumer's `Show when={field()}`
+        // permanently stuck on its fallback (typically a static `<p>` with
+        // no editing UI), with no error trail. Surface the failure so the
+        // root cause (missing `@crdt` annotation, schema codegen drift,
+        // local DB query failure, etc.) is visible in the console instead
+        // of silently breaking collaborative fields.
+        console.error(
+          `[useCrdtField] Failed to open CRDT field ${table}.${field} on ${id}:`,
+          err,
+        );
+      });
+  });
+
+  onCleanup(() => {
+    if (currentId && crdtField()) {
+      db.getSp00ky().closeCrdtField(table, currentId, field);
+      setCrdtField(null);
+    }
+  });
+
+  return crdtField;
+}

package/src/lib/use-download-file.ts

@@ -78,9 +78,8 @@ export function useDownloadFile<S extends SchemaStructure>(
 
   let currentKey: string | null = null;
   let privateUrl: string | null = null;
-  let refetchTrigger: () => void;
   const [refetchSignal, setRefetchSignal] = createSignal(0);
-  refetchTrigger = () => setRefetchSignal((n) => n + 1);
+  const refetchTrigger = () => setRefetchSignal((n) => n + 1);
 
   async function doDownload(key: string, filePath: string): Promise<string | null> {
     if (useCache) {
@@ -184,6 +183,7 @@ export function useDownloadFile<S extends SchemaStructure>(
           setUrl(result);
           setIsLoading(false);
         }
+        return undefined;
       },
       (err) => {
         if (!cancelled) {

package/src/lib/use-feature-flag.ts

@@ -0,0 +1,50 @@
+import { createSignal, onCleanup, type Accessor } from 'solid-js';
+import { useDb } from './context';
+import type { FeatureFlagOptions } from '@spooky-sync/core';
+
+export interface UseFeatureFlag {
+  variant: Accessor<string | undefined>;
+  payload: Accessor<unknown | undefined>;
+  enabled: Accessor<boolean>;
+}
+
+/**
+ * Subscribe to a feature flag for the currently authenticated user.
+ *
+ * Returns three Solid accessors that update reactively whenever the
+ * server-materialized assignment in `_00_user_feature` changes. Backed by
+ * the same SSP + sync pipeline that powers `useQuery`, so toggling a flag
+ * via `spky flag enable <key>` propagates to the UI without a refresh.
+ *
+ * `enabled()` is `true` when the resolved variant exists and is not 'off'.
+ * For multi-variant flags, prefer `variant()` directly.
+ */
+export function useFeatureFlag(
+  key: string,
+  options?: FeatureFlagOptions,
+): UseFeatureFlag {
+  const db = useDb();
+  const handle = db.getSp00ky().feature(key, options);
+
+  const [variant, setVariant] = createSignal<string | undefined>(handle.variant());
+  const [payload, setPayload] = createSignal<unknown | undefined>(handle.payload());
+
+  const unsub = handle.subscribe((s) => {
+    setVariant(s.variant ?? options?.fallback);
+    setPayload(s.payload);
+  });
+
+  onCleanup(() => {
+    unsub();
+    handle.close();
+  });
+
+  return {
+    variant,
+    payload,
+    enabled: () => {
+      const v = variant();
+      return v !== undefined && v !== 'off';
+    },
+  };
+}

package/src/lib/use-file-upload.ts

@@ -33,6 +33,7 @@ export function useFileUpload<S extends SchemaStructure>(
     bucketName = dbOrBucketName as BucketNames<S>;
   } else {
     db = dbOrBucketName as SyncedDb<S>;
+    // oxlint-disable-next-line no-non-null-assertion
     bucketName = maybeBucketName!;
   }
 
@@ -52,7 +53,7 @@ export function useFileUpload<S extends SchemaStructure>(
     const config = db.getBucketConfig(bucketName as string);
     if (!config) return;
 
-    if (config.maxSize != null && file.size > config.maxSize) {
+    if (config.maxSize !== null && config.maxSize !== undefined && file.size > config.maxSize) {
       const maxMB = (config.maxSize / (1024 * 1024)).toFixed(1);
       throw new Error(`File exceeds maximum size of ${maxMB} MB.`);
     }