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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/client-solid",
-  "version": "0.0.1-canary.9",
+  "version": "0.0.1-canary.90",
   "type": "module",
   "description": "SurrealDB client with local and remote database support for browser applications",
   "main": "./dist/index.cjs",
@@ -27,13 +27,14 @@
     "database",
     "browser",
     "offline",
-    "sync"
+    "sync",
+    "tanstack-intent"
   ],
   "author": "",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/mono424/spooky.git",
+    "url": "https://github.com/mono424/sp00ky.git",
     "directory": "packages/client-solid"
   },
   "publishConfig": {
@@ -41,10 +42,10 @@
   },
   "packageManager": "pnpm@9.0.0",
   "dependencies": {
-    "@spooky-sync/query-builder": "workspace:*",
-    "@spooky-sync/core": "workspace:*",
-    "@surrealdb/wasm": "^3.0.0",
-    "surrealdb": "2.0.0",
+    "@spooky-sync/query-builder": "0.0.1-canary.90",
+    "@spooky-sync/core": "0.0.1-canary.90",
+    "@surrealdb/wasm": "^3.0.3",
+    "surrealdb": "2.0.3",
     "valtio": "^2.1.8"
   },
   "peerDependencies": {

package/skills/sp00ky-solid/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: sp00ky-solid
+description: >-
+  SolidJS integration for the Sp00ky reactive local-first SurrealDB framework.
+  Use when setting up Sp00kyProvider, using useQuery for reactive data, building
+  queries with QueryBuilder in SolidJS components, handling mutations, auth,
+  file uploads/downloads, or working with Sp00ky types like Model and RecordId.
+metadata:
+  author: sp00ky-sync
+  version: "0.0.1"
+---
+
+# Sp00ky SolidJS Client
+
+`@spooky-sync/client-solid` provides SolidJS bindings for the Sp00ky framework. It wraps `@spooky-sync/core` with a context provider, reactive `useQuery` hook, and file operation hooks.
+
+## Setup
+
+```tsx
+import { Sp00kyProvider } from '@spooky-sync/client-solid';
+import { schema } from './generated/schema';
+import schemaSurql from './generated/schema.surql?raw';
+
+function App() {
+  return (
+    <Sp00kyProvider
+      config={{
+        database: {
+          endpoint: 'ws://localhost:8000',
+          namespace: 'my_ns',
+          database: 'my_db',
+          store: 'indexeddb',
+        },
+        schema,
+        schemaSurql,
+        logLevel: 'info',
+      }}
+      fallback={<div>Loading database...</div>}
+      onReady={(db) => console.log('DB ready')}
+      onError={(err) => console.error('DB failed', err)}
+    >
+      <MyApp />
+    </Sp00kyProvider>
+  );
+}
+```
+
+### Sp00kyProvider Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `config` | `SyncedDbConfig<S>` | Same as `Sp00kyConfig` from core |
+| `fallback` | `JSX.Element` | Shown while the database is initializing |
+| `onReady` | `(db: SyncedDb<S>) => void` | Called when initialization succeeds |
+| `onError` | `(error: Error) => void` | Called if initialization fails |
+| `children` | `JSX.Element` | App content, rendered after init |
+
+## useQuery
+
+The primary hook for reactive data fetching. Queries automatically re-subscribe when inputs change.
+
+### Context-based usage (recommended)
+
+```tsx
+import { useQuery } from '@spooky-sync/client-solid';
+import { QueryBuilder } from '@spooky-sync/query-builder';
+import { schema } from './generated/schema';
+
+function PostList() {
+  const db = useDb();
+
+  // Static query
+  const posts = useQuery(
+    db.query('post').orderBy('createdAt', 'desc').limit(20).build()
+  );
+
+  return (
+    <Show when={!posts.isLoading()} fallback={<div>Loading...</div>}>
+      <For each={posts.data()}>
+        {(post) => <div>{post.title}</div>}
+      </For>
+    </Show>
+  );
+}
+```
+
+### Reactive queries (function form)
+
+Wrap the query in a function to make it reactive to signal changes:
+
+```tsx
+function UserPosts(props: { userId: string }) {
+  const db = useDb();
+
+  // Query re-runs when props.userId changes
+  const posts = useQuery(
+    () => db.query('post')
+      .where({ author: props.userId })
+      .related('author')
+      .build()
+  );
+
+  return <For each={posts.data()}>{(post) => <div>{post.title}</div>}</For>;
+}
+```
+
+### Conditional queries
+
+Use the `enabled` option to conditionally run queries:
+
+```tsx
+const [userId, setUserId] = createSignal<string | null>(null);
+
+const user = useQuery(
+  () => userId()
+    ? db.query('user').where({ id: userId()! }).one().build()
+    : undefined,
+  { enabled: () => userId() !== null }
+);
+```
+
+### Return value
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data` | `() => T \| undefined` | Reactive accessor for query results |
+| `error` | `() => Error \| undefined` | Reactive accessor for errors |
+| `isLoading` | `() => boolean` | `true` until first data arrives |
+
+### Explicit db overload
+
+You can also pass the `SyncedDb` instance directly (legacy):
+
+```tsx
+const posts = useQuery(db, db.query('post').build());
+```
+
+## useDb
+
+Access the `SyncedDb` instance from context:
+
+```tsx
+import { useDb } from '@spooky-sync/client-solid';
+
+function MyComponent() {
+  const db = useDb();
+  // db.query(), db.create(), db.update(), db.delete(), db.auth, etc.
+}
+```
+
+## Mutations
+
+Use the `SyncedDb` instance (from `useDb()`) for mutations:
+
+```tsx
+const db = useDb();
+
+// Create
+await db.create('post:abc', { title: 'Hello', body: 'World', author: 'user:alice' });
+
+// Update
+await db.update('post', 'post:abc', { title: 'Updated' });
+
+// Update with debounce
+await db.update('post', 'post:abc', { body: newText }, {
+  debounced: { key: 'recordId_x_fields', delay: 300 },
+});
+
+// Delete
+await db.delete('post', 'post:abc');
+```
+
+## Authentication
+
+```tsx
+const db = useDb();
+
+await db.auth.signUp('user_access', { email, password, name });
+await db.auth.signIn('user_access', { email, password });
+await db.auth.signOut();
+
+// Subscribe to auth state
+const unsub = db.auth.subscribe((userId) => { ... });
+```
+
+## File Upload & Download
+
+See [references/file-hooks.md](references/file-hooks.md) for details.
+
+```tsx
+import { useFileUpload, useDownloadFile } from '@spooky-sync/client-solid';
+
+// Upload
+const { upload, isUploading, error } = useFileUpload('avatars');
+await upload('alice/photo.png', file);
+
+// Download (reactive)
+const { url, isLoading } = useDownloadFile('avatars', () => user()?.avatarPath);
+```
+
+## Backend Runs
+
+Use `db.run()` to trigger server-side operations via the outbox pattern. See the `sp00ky-core` skill for full details on `db.run()` and how it works.
+
+### Basic Usage
+
+```tsx
+const db = useDb();
+await db.run('api', '/spookify', { id: threadId });
+```
+
+### Entity Linking with `assignedTo`
+
+Pass `assignedTo` to link the job to an entity. This enables permission scoping and lets you query job status via relationships:
+
+```tsx
+const db = useDb();
+
+// Trigger backend run linked to a thread
+await db.run('api', '/spookify', { id: threadData.id }, {
+  assignedTo: threadData.id,  // Links the job record to this thread
+});
+```
+
+### Tracking Job Status Reactively
+
+Use `.related()` to include jobs in your query, then reactively track their status:
+
+```tsx
+// Query a thread with its latest spookify job
+const threadResult = useQuery(() =>
+  db.query('thread')
+    .where({ id: `thread:${threadId}` })
+    .related('jobs', (q) =>
+      q.where({ path: '/spookify' }).orderBy('created_at', 'desc').limit(1)
+    )
+    .one()
+    .build()
+);
+
+const thread = () => threadResult.data();
+
+// Check if a job is in progress
+const isJobLoading = () =>
+  ['pending', 'processing'].includes(thread()?.jobs?.[0]?.status ?? '');
+
+// Use in UI
+<Show when={isJobLoading()}>
+  <span>Processing...</span>
+</Show>
+```
+
+The job's `status` field transitions through: `pending` → `processing` → `success` | `failed`. Since the job record syncs reactively, your UI updates automatically as the backend processes the job.
+
+## Key Re-exports
+
+The package re-exports commonly needed types:
+
+```typescript
+import { RecordId, Uuid } from '@spooky-sync/client-solid';
+import type {
+  Model, GenericModel, QueryResult, TableModel, TableNames, GetTable,
+} from '@spooky-sync/client-solid';
+```

package/skills/sp00ky-solid/references/file-hooks.md

@@ -0,0 +1,112 @@
+# File Hooks Reference
+
+## useFileUpload
+
+Upload, download, and manage files in a SurrealDB bucket.
+
+### Signatures
+
+```typescript
+// Context-based (inside Sp00kyProvider)
+useFileUpload<S>(bucketName: BucketNames<S>): FileUploadResult;
+
+// Explicit db
+useFileUpload<S>(db: SyncedDb<S>, bucketName: BucketNames<S>): FileUploadResult;
+```
+
+### Return Value
+
+```typescript
+interface FileUploadResult {
+  isUploading: () => boolean;
+  error: () => Error | null;
+  clearError: () => void;
+  upload: (path: string, file: File | Blob) => Promise<void>;
+  download: (path: string) => Promise<string | null>; // Returns object URL
+  remove: (path: string) => Promise<void>;
+  exists: (path: string) => Promise<boolean>;
+}
+```
+
+### Validation
+
+If the bucket has `maxSize` or `allowedExtensions` configured in the schema, the hook validates files before upload and sets `error()` on failure.
+
+### Example
+
+```tsx
+function AvatarUpload() {
+  const { upload, isUploading, error, clearError } = useFileUpload('avatars');
+
+  const handleFile = async (e: Event) => {
+    const file = (e.target as HTMLInputElement).files?.[0];
+    if (file) {
+      await upload(`user/${userId()}/avatar.png`, file);
+    }
+  };
+
+  return (
+    <div>
+      <input type="file" onChange={handleFile} disabled={isUploading()} />
+      <Show when={error()}>
+        <p class="error">{error()!.message}</p>
+        <button onClick={clearError}>Dismiss</button>
+      </Show>
+    </div>
+  );
+}
+```
+
+## useDownloadFile
+
+Reactively download a file from a bucket. Re-fetches when the path changes.
+
+### Signatures
+
+```typescript
+// Context-based
+useDownloadFile<S>(
+  bucketName: BucketNames<S>,
+  path: Accessor<string | null | undefined>,
+  options?: { cache?: boolean },
+): UseDownloadFileResult;
+
+// Explicit db
+useDownloadFile<S>(
+  db: SyncedDb<S>,
+  bucketName: BucketNames<S>,
+  path: Accessor<string | null | undefined>,
+  options?: { cache?: boolean },
+): UseDownloadFileResult;
+```
+
+### Return Value
+
+```typescript
+interface UseDownloadFileResult {
+  url: Accessor<string | null>;     // Object URL for the file
+  isLoading: Accessor<boolean>;
+  error: Accessor<Error | null>;
+  refetch: () => void;              // Force re-download (evicts cache)
+}
+```
+
+### Caching
+
+By default, downloads are cached by `bucket:path` key with reference counting. Object URLs are revoked when no component references them. Set `cache: false` to disable.
+
+### Example
+
+```tsx
+function Avatar(props: { path: string | null }) {
+  const { url, isLoading } = useDownloadFile('avatars', () => props.path);
+
+  return (
+    <Show when={!isLoading()} fallback={<Spinner />}>
+      <Show when={url()}>
+        <img src={url()!} alt="Avatar" />
+      </Show>
+    </Show>
+  );
+}
+```

package/src/cache/index.ts

@@ -1,6 +1,6 @@
 export { SurrealDBWasmFactory } from './surrealdb-wasm-factory';
 
-import { Surreal } from 'surrealdb';
+import type { Surreal } from 'surrealdb';
 import type { CacheStrategy } from '../types';
 
 /**

package/src/cache/surrealdb-wasm-factory.ts

@@ -1,9 +1,11 @@
-import { Diagnostic, Surreal, applyDiagnostics } from 'surrealdb';
+import type { Diagnostic} from 'surrealdb';
+import { Surreal, applyDiagnostics } from 'surrealdb';
 import { createWasmEngines } from '@surrealdb/wasm';
 import type { CacheStrategy } from '../types';
 
 const printDiagnostic = ({ key, type, phase, ...other }: Diagnostic) => {
   if (phase === 'progress' || phase === 'after') {
+    // oxlint-disable-next-line no-console -- intentional diagnostic logging
     console.log(`[SurrealDB_WASM] [${key}] ${type}:${phase}\n${JSON.stringify(other, null, 2)}`);
   }
 };
@@ -11,6 +13,7 @@ const printDiagnostic = ({ key, type, phase, ...other }: Diagnostic) => {
 /**
  * SurrealDB WASM client factory for different storage strategies
  */
+// oxlint-disable-next-line no-extraneous-class -- factory pattern groups related static methods
 export class SurrealDBWasmFactory {
   /**
    * Creates a SurrealDB WASM instance with the specified storage strategy