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

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,175 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from 'solid-js';
+import type { SchemaStructure, BucketNames } from '@spooky-sync/query-builder';
+import type { BlobUrlLease } from '@spooky-sync/core';
+import type { SyncedDb } from '../index';
+import { useDb } from './context';
+
+export interface UseDownloadFileOptions {
+  /**
+   * Master switch, default `true`. `false` gives every hook instance its own
+   * private object URL fetched fresh from the bucket and revoked on unmount —
+   * no sharing, no persistence, no reuse.
+   */
+  cache?: boolean;
+  /**
+   * Keep the bytes in OPFS so they survive a reload and are available offline.
+   * Default `true`. Turn off for one-shot or sensitive files; the in-tab object
+   * URL is still shared between components rendering the same path.
+   */
+  persist?: boolean;
+  /** Exempt this file from pressure eviction. Pinned bytes never expire. */
+  pin?: boolean;
+  /**
+   * `'never'` (default) treats a bucket path as immutable, which is how paths
+   * are written (`crypto.randomUUID() + ext`). `'head'` spends a remote `head()`
+   * to compare sizes before trusting the cached copy — for paths the app
+   * overwrites in place.
+   */
+  revalidate?: 'never' | 'head';
+}
+
+export interface UseDownloadFileResult {
+  url: Accessor<string | null>;
+  isLoading: Accessor<boolean>;
+  error: Accessor<Error | null>;
+  refetch: () => void;
+}
+
+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);
+
+  // Exactly one of these is held at a time: a refcounted lease on the shared
+  // cache entry, or a private URL this instance minted and must revoke itself.
+  let lease: BlobUrlLease | null = null;
+  let privateUrl: string | null = null;
+
+  const [refetchSignal, setRefetchSignal] = createSignal(0);
+  /** Consumed by the next effect run, so `refetch()` bypasses every layer once. */
+  let reloadOnce = false;
+
+  function releaseCurrent() {
+    lease?.release();
+    lease = null;
+    if (privateUrl) {
+      URL.revokeObjectURL(privateUrl);
+      privateUrl = null;
+    }
+  }
+
+  createEffect(() => {
+    const filePath = path();
+    // Subscribe to refetch signal so effect re-runs
+    refetchSignal();
+
+    releaseCurrent();
+
+    if (!filePath) {
+      setUrl(null);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    const reload = reloadOnce;
+    reloadOnce = false;
+
+    let cancelled = false;
+    setIsLoading(true);
+    setError(null);
+
+    const bucket = db.bucket(bucketName);
+    const resolve = useCache
+      ? bucket
+          .url(filePath, {
+            persist: options.persist !== false,
+            pin: options.pin,
+            revalidate: options.revalidate,
+            reload,
+          })
+          .then((acquired) => {
+            if (!acquired) return null;
+            if (cancelled) {
+              // Unmounted or the path changed mid-flight — hand the reference
+              // straight back, or the entry never drops to zero and its object
+              // URL leaks for the life of the tab.
+              acquired.release();
+              return null;
+            }
+            lease = acquired;
+            return acquired.url;
+          })
+      : bucket.read(filePath, { persist: false, reload: true }).then((blob) => {
+          if (!blob || cancelled) return null;
+          privateUrl = URL.createObjectURL(blob);
+          return privateUrl;
+        });
+
+    resolve.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(() => {
+    releaseCurrent();
+  });
+
+  const refetch = () => {
+    reloadOnce = true;
+    setRefetchSignal((n) => n + 1);
+  };
+
+  return { url, isLoading, error, refetch };
+}

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

@@ -0,0 +1,141 @@
+import { createSignal, onCleanup } from 'solid-js';
+import type { SchemaStructure, BucketNames } from '@spooky-sync/query-builder';
+import { fileToUint8Array } from '@spooky-sync/core';
+import type { BucketPutOptions, BucketPutResult } from '@spooky-sync/core';
+import type { SyncedDb } from '../index';
+import { useDb } from './context';
+
+export interface FileUploadResult {
+  isUploading: () => boolean;
+  error: () => Error | null;
+  clearError: () => void;
+  upload: (path: string, file: File | Blob, options?: BucketPutOptions) => Promise<BucketPutResult | void>;
+  download: (path: string) => Promise<string | null>;
+  remove: (path: string) => Promise<void>;
+  exists: (path: string) => Promise<boolean>;
+}
+
+export function useFileUpload<S extends SchemaStructure>(
+  bucketName: BucketNames<S>,
+): FileUploadResult;
+export function useFileUpload<S extends SchemaStructure>(
+  db: SyncedDb<S>,
+  bucketName: BucketNames<S>,
+): FileUploadResult;
+export function useFileUpload<S extends SchemaStructure>(
+  dbOrBucketName: SyncedDb<S> | BucketNames<S>,
+  maybeBucketName?: BucketNames<S>,
+): FileUploadResult {
+  let db: SyncedDb<S>;
+  let bucketName: BucketNames<S>;
+
+  if (typeof dbOrBucketName === 'string') {
+    db = useDb<S>();
+    bucketName = dbOrBucketName as BucketNames<S>;
+  } else {
+    db = dbOrBucketName as SyncedDb<S>;
+    // oxlint-disable-next-line no-non-null-assertion
+    bucketName = maybeBucketName!;
+  }
+
+  const [isUploading, setIsUploading] = createSignal(false);
+  const [error, setError] = createSignal<Error | null>(null);
+
+  const objectUrls: string[] = [];
+  onCleanup(() => {
+    for (const url of objectUrls) {
+      URL.revokeObjectURL(url);
+    }
+  });
+
+  const clearError = () => setError(null);
+
+  const validate = (file: File | Blob): void => {
+    const config = db.getBucketConfig(bucketName as string);
+    if (!config) return;
+
+    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.`);
+    }
+
+    if (config.allowedExtensions && config.allowedExtensions.length > 0) {
+      const fileName = (file as File).name;
+      if (fileName) {
+        const ext = fileName.split('.').pop()?.toLowerCase();
+        if (!ext || !config.allowedExtensions.includes(ext)) {
+          throw new Error(
+            `File type not allowed. Accepted: ${config.allowedExtensions.join(', ')}.`
+          );
+        }
+      }
+    }
+  };
+
+  const upload = async (
+    path: string,
+    file: File | Blob,
+    options?: BucketPutOptions
+  ): Promise<BucketPutResult | void> => {
+    setError(null);
+    try {
+      validate(file);
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+      return;
+    }
+
+    setIsUploading(true);
+    try {
+      const bytes = await fileToUint8Array(file);
+      return await db.bucket(bucketName).put(path, bytes, options);
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+    } finally {
+      setIsUploading(false);
+    }
+  };
+
+  const download = async (path: string): Promise<string | null> => {
+    setError(null);
+    try {
+      const content = await db.bucket(bucketName).get(path);
+      if (!content) return null;
+      const objectUrl = URL.createObjectURL(new Blob([content as BlobPart]));
+      objectUrls.push(objectUrl);
+      return objectUrl;
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+      return null;
+    }
+  };
+
+  const remove = async (path: string): Promise<void> => {
+    setError(null);
+    try {
+      await db.bucket(bucketName).delete(path);
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+    }
+  };
+
+  const exists = async (path: string): Promise<boolean> => {
+    setError(null);
+    try {
+      return await db.bucket(bucketName).exists(path);
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+      return false;
+    }
+  };
+
+  return {
+    isUploading,
+    error,
+    clearError,
+    upload,
+    download,
+    remove,
+    exists,
+  };
+}