@spooky-sync/client-solid 0.0.1-canary.1 → 0.0.1-canary.100

package/src/index.ts

@@ -1,13 +1,15 @@
 import type { SyncedDbConfig } from './types';
 import {
-  SpookyClient,
-  AuthService,
-  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,
@@ -22,17 +24,32 @@ import {
   BackendNames,
   BackendRoutes,
   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 { SpookyProvider, type SpookyProviderProps } from './lib/SpookyProvider';
+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 { 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 {
@@ -47,7 +64,7 @@ export type {
   TableModel,
   TableNames,
   QueryResult,
-} from '@spooky-sync/query-builder';
+};
 
 export type RelationshipField<
   Schema extends SchemaStructure,
@@ -89,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;
   }
 
@@ -120,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>);
   }
 
   /**
@@ -133,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>,
@@ -147,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);
   }
 
   /**
@@ -160,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, {});
   }
 
   /**
@@ -177,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?
@@ -205,49 +236,80 @@ 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.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.bucket(name);
+  }
+
+  getBucketConfig(name: string): BucketDefinitionSchema | undefined {
+    return this.config.schema.buckets?.find((b) => b.name === name);
   }
 }
 

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

@@ -0,0 +1,219 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from 'solid-js';
+import type { SchemaStructure, BucketNames } from '@spooky-sync/query-builder';
+import type { SyncedDb } from '../index';
+import { useDb } from './context';
+
+export interface UseDownloadFileOptions {
+  cache?: boolean;
+}
+
+export interface UseDownloadFileResult {
+  url: Accessor<string | null>;
+  isLoading: Accessor<boolean>;
+  error: Accessor<Error | null>;
+  refetch: () => void;
+}
+
+interface CacheEntry {
+  url: string;
+  refCount: number;
+}
+
+const downloadCache = new Map<string, CacheEntry>();
+const inflightRequests = new Map<string, Promise<string | null>>();
+
+function cacheKey(bucket: string, path: string): string {
+  return `${bucket}:${path}`;
+}
+
+function releaseEntry(key: string): void {
+  const entry = downloadCache.get(key);
+  if (!entry) return;
+  entry.refCount--;
+  if (entry.refCount <= 0) {
+    URL.revokeObjectURL(entry.url);
+    downloadCache.delete(key);
+  }
+}
+
+export function useDownloadFile<S extends SchemaStructure>(
+  bucketName: BucketNames<S>,
+  path: Accessor<string | null | undefined>,
+  options?: UseDownloadFileOptions,
+): UseDownloadFileResult;
+export function useDownloadFile<S extends SchemaStructure>(
+  db: SyncedDb<S>,
+  bucketName: BucketNames<S>,
+  path: Accessor<string | null | undefined>,
+  options?: UseDownloadFileOptions,
+): UseDownloadFileResult;
+export function useDownloadFile<S extends SchemaStructure>(
+  dbOrBucketName: SyncedDb<S> | BucketNames<S>,
+  bucketNameOrPath?: BucketNames<S> | Accessor<string | null | undefined>,
+  pathOrOptions?: Accessor<string | null | undefined> | UseDownloadFileOptions,
+  maybeOptions?: UseDownloadFileOptions,
+): UseDownloadFileResult {
+  let db: SyncedDb<S>;
+  let bucketName: BucketNames<S>;
+  let path: Accessor<string | null | undefined>;
+  let options: UseDownloadFileOptions;
+
+  if (typeof dbOrBucketName === 'string') {
+    db = useDb<S>();
+    bucketName = dbOrBucketName as BucketNames<S>;
+    path = bucketNameOrPath as Accessor<string | null | undefined>;
+    options = (pathOrOptions as UseDownloadFileOptions) ?? {};
+  } else {
+    db = dbOrBucketName as SyncedDb<S>;
+    bucketName = bucketNameOrPath as BucketNames<S>;
+    path = pathOrOptions as Accessor<string | null | undefined>;
+    options = maybeOptions ?? {};
+  }
+
+  const useCache = options.cache !== false;
+
+  const [url, setUrl] = createSignal<string | null>(null);
+  const [isLoading, setIsLoading] = createSignal(false);
+  const [error, setError] = createSignal<Error | null>(null);
+
+  let currentKey: string | null = null;
+  let privateUrl: string | null = null;
+  const [refetchSignal, setRefetchSignal] = createSignal(0);
+  const refetchTrigger = () => setRefetchSignal((n) => n + 1);
+
+  async function doDownload(key: string, filePath: string): Promise<string | null> {
+    if (useCache) {
+      // Check cache
+      const cached = downloadCache.get(key);
+      if (cached) {
+        cached.refCount++;
+        currentKey = key;
+        return cached.url;
+      }
+
+      // Check inflight
+      const inflight = inflightRequests.get(key);
+      if (inflight) {
+        const result = await inflight;
+        if (result) {
+          const entry = downloadCache.get(key);
+          if (entry) {
+            entry.refCount++;
+            currentKey = key;
+          }
+        }
+        return result;
+      }
+
+      // Start new download
+      const promise = (async () => {
+        const content = await db.bucket(bucketName).get(filePath);
+        if (!content) return null;
+        const objectUrl = URL.createObjectURL(new Blob([content as BlobPart]));
+        downloadCache.set(key, { url: objectUrl, refCount: 1 });
+        return objectUrl;
+      })();
+
+      inflightRequests.set(key, promise);
+      try {
+        const result = await promise;
+        currentKey = key;
+        return result;
+      } finally {
+        inflightRequests.delete(key);
+      }
+    } else {
+      // No caching — private URL per instance
+      const content = await db.bucket(bucketName).get(filePath);
+      if (!content) return null;
+      const objectUrl = URL.createObjectURL(new Blob([content as BlobPart]));
+      privateUrl = objectUrl;
+      return objectUrl;
+    }
+  }
+
+  function releaseCurrentEntry() {
+    if (useCache && currentKey) {
+      releaseEntry(currentKey);
+      currentKey = null;
+    }
+    if (!useCache && privateUrl) {
+      URL.revokeObjectURL(privateUrl);
+      privateUrl = null;
+    }
+  }
+
+  createEffect(() => {
+    const filePath = path();
+    // Subscribe to refetch signal so effect re-runs
+    refetchSignal();
+
+    // Release previous entry
+    releaseCurrentEntry();
+
+    if (!filePath) {
+      setUrl(null);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    const key = cacheKey(bucketName as string, filePath);
+
+    // Synchronous cache hit
+    if (useCache) {
+      const cached = downloadCache.get(key);
+      if (cached) {
+        cached.refCount++;
+        currentKey = key;
+        setUrl(cached.url);
+        setIsLoading(false);
+        setError(null);
+        return;
+      }
+    }
+
+    let cancelled = false;
+    setIsLoading(true);
+    setError(null);
+
+    doDownload(key, filePath).then(
+      (result) => {
+        if (!cancelled) {
+          setUrl(result);
+          setIsLoading(false);
+        }
+        return undefined;
+      },
+      (err) => {
+        if (!cancelled) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+          setIsLoading(false);
+        }
+      },
+    );
+
+    onCleanup(() => {
+      cancelled = true;
+    });
+  });
+
+  onCleanup(() => {
+    releaseCurrentEntry();
+  });
+
+  const refetch = () => {
+    // Evict current entry from cache before re-triggering
+    if (useCache && currentKey) {
+      const entry = downloadCache.get(currentKey);
+      if (entry) {
+        URL.revokeObjectURL(entry.url);
+        downloadCache.delete(currentKey);
+      }
+      currentKey = null;
+    }
+    refetchTrigger();
+  };
+
+  return { url, isLoading, error, refetch };
+}