@spooky-sync/client-solid2 0.0.1-canary.355 → 0.0.1-canary.356

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spooky-sync/client-solid2",
3
- "version": "0.0.1-canary.355",
3
+ "version": "0.0.1-canary.356",
4
4
  "type": "module",
5
5
  "sideEffects": false,
6
6
  "description": "Solid 2 native bindings for the sp00ky sync client",
@@ -43,8 +43,8 @@
43
43
  },
44
44
  "packageManager": "pnpm@9.0.0",
45
45
  "dependencies": {
46
- "@spooky-sync/query-builder": "0.0.1-canary.355",
47
- "@spooky-sync/core": "0.0.1-canary.355",
46
+ "@spooky-sync/query-builder": "0.0.1-canary.356",
47
+ "@spooky-sync/core": "0.0.1-canary.356",
48
48
  "@surrealdb/wasm": "^3.1.0",
49
49
  "surrealdb": "2.1.0"
50
50
  },
@@ -51,6 +51,24 @@ Returns `{ data, ready, error, isLoading, isFetching, isAuthoritative, hasData,
51
51
 
52
52
  Rows are Solid 2 store proxies; class instances (RecordId) are proxied with bound methods. `db.delete('table', row.id)` works; for surrealdb APIs that check `instanceof`, unwrap with `snapshot(row)` first.
53
53
 
54
+ ## Peer to peer channels (experimental)
55
+
56
+ Mark a table `-- @channel` (and peer-only fields `-- @ephemeral`, which must be `option<...>`), then open a channel over the rows of a query for the component's lifetime:
57
+
58
+ ```ts
59
+ const ch = useChannel(
60
+ () => db.query('message').where({ conversation: convoId() }), // only the where counts
61
+ () => [me(), other()]
62
+ );
63
+ ch.status(); // 'idle' | 'connecting' | 'connected' | 'failed' | 'unsupported'
64
+
65
+ // No new write API: writes to rows matching the filter reach the peers over WebRTC,
66
+ // and every createQuery showing the row reflects them. @ephemeral fields never hit the DB.
67
+ await db.create('message:' + crypto.randomUUID(), { conversation: convoId(), text });
68
+ ```
69
+
70
+ Typed from the query. `orderBy` / `limit` / `select` / `.one()` are ignored by a channel and warn; add `.ignoreUnusedArgs()` when the query is shared with a list on purpose. Peer writes are claims: normal fields, creates and deletes show until the server confirms them (5 s max), ephemeral fields last writer wins. Decide what to accept per table with the client config `channels.accept`. Docs: `/docs/client/channels`.
71
+
54
72
  ## Mutations
55
73
 
56
74
  Engine is optimistic local-first end to end (local commit → live re-emit → outbox sync; `db.run()` creates an outbox job row `status: 'pending'`). Use plain `db.create/update/delete/run`. For UI pending/error state:
package/src/index.ts CHANGED
@@ -11,9 +11,13 @@ import {
11
11
  type PreloadOptions,
12
12
  type PreloadRefresh,
13
13
  type WebPushModule,
14
+ type Sp00kyChannel,
15
+ type ChannelQuery,
14
16
  } from '@spooky-sync/core';
15
17
 
16
18
  import type {
19
+ ChannelPeer,
20
+ ChannelTableNames,
17
21
  GetTable,
18
22
  QueryBuilder,
19
23
  SchemaStructure,
@@ -89,6 +93,8 @@ export {
89
93
  type PushNotification,
90
94
  } from '@spooky-sync/core';
91
95
  export { useCrdtField } from './lib/use-crdt-field';
96
+ export { useChannel, type UseChannel, type ChannelPeers, type ChannelQueries } from './lib/use-channel';
97
+ export type { ChannelState, ChannelStatus, ChannelOp, ChannelsConfig, Sp00kyChannel } from '@spooky-sync/core';
92
98
  export { useFeatureFlag, type UseFeatureFlag } from './lib/use-feature-flag';
93
99
  export {
94
100
  useAppRelease,
@@ -309,6 +315,19 @@ export class SyncedDb<S extends SchemaStructure> {
309
315
  return this.sp00ky.query(table, {});
310
316
  }
311
317
 
318
+ /**
319
+ * Open a peer to peer channel to `peers` for the rows `query` matches (a
320
+ * query on a `-- @channel` table; only its `where` counts). Prefer the
321
+ * `useChannel` hook, which closes it with the component.
322
+ */
323
+ public channel<T extends ChannelTableNames<S>>(
324
+ query: ChannelQuery<S, T> | ReadonlyArray<ChannelQuery<S, T>>,
325
+ peers: Iterable<ChannelPeer>
326
+ ): Sp00kyChannel<S, T> {
327
+ if (!this.sp00ky) throw new Error('SyncedDb not initialized');
328
+ return this.sp00ky.channel(query, peers);
329
+ }
330
+
312
331
  /**
313
332
  * Run a backend operation
314
333
  */
@@ -0,0 +1,52 @@
1
+ import { describe, expect, it } from 'vitest';
2
+ import type { SyncedDb } from '../..';
3
+ import { useChannel } from '../use-channel';
4
+
5
+ // Type-level checks: `tsc` runs over this file, the body never executes.
6
+ const schema = {
7
+ tables: [
8
+ {
9
+ name: 'message' as const,
10
+ columns: {
11
+ id: { type: 'string' as const, optional: false, recordId: true },
12
+ text: { type: 'string' as const, optional: false },
13
+ typing: { type: 'number' as const, optional: true, ephemeral: true },
14
+ },
15
+ channel: true as const,
16
+ primaryKey: ['id'] as const,
17
+ },
18
+ {
19
+ name: 'note' as const,
20
+ columns: { id: { type: 'string' as const, optional: false, recordId: true } },
21
+ primaryKey: ['id'] as const,
22
+ },
23
+ ],
24
+ relationships: [],
25
+ backends: {},
26
+ } as const;
27
+
28
+ function typed(db: SyncedDb<typeof schema>) {
29
+ const ch = useChannel(db.query('message').where({ text: 'x' }), ['user:a', 'user:b']);
30
+ void ch.update('message', 'message:1', { typing: Date.now() });
31
+ void ch.create('message:1', { text: 'hi' });
32
+ void ch.delete('message', 'message:1');
33
+ // @ts-expect-error unknown field
34
+ void ch.update('message', 'message:1', { nope: 1 });
35
+ // @ts-expect-error the id must name a carried table
36
+ void ch.create('note:1', {});
37
+ // @ts-expect-error `note` is not a -- @channel table
38
+ useChannel(db.query('note'), []);
39
+ // Accessor, built query, a list, and the explicit opt-out all type-check.
40
+ useChannel(() => db.query('message').where({ text: 'x' }), () => ['user:b']);
41
+ useChannel(db.query('message').build(), []);
42
+ useChannel([db.query('message')], []);
43
+ useChannel(db.query('message').limit(50).ignoreUnusedArgs(), []);
44
+ // @ts-expect-error a table name is not a channel any more
45
+ useChannel('message', []);
46
+ }
47
+
48
+ describe('useChannel types', () => {
49
+ it('compiles', () => {
50
+ expect(typeof typed).toBe('function');
51
+ });
52
+ });
@@ -0,0 +1,92 @@
1
+ import { createEffect, createSignal, onCleanup, untrack } from 'solid-js';
2
+ import type { ChannelPeer, ChannelTableNames, SchemaStructure } from '@spooky-sync/query-builder';
3
+ import type { ChannelQuery, ChannelState, ChannelStatus, Sp00kyChannel } from '@spooky-sync/core';
4
+ import type { SyncedDb } from '..';
5
+ import { useDb } from './context';
6
+
7
+ /** Who a channel connects to: a list, or an accessor of one (re-read when it changes). */
8
+ export type ChannelPeers = Iterable<ChannelPeer> | (() => Iterable<ChannelPeer> | null | undefined);
9
+
10
+ /** What a channel carries: the rows a query (or several) matches. */
11
+ export type ChannelQueries<S extends SchemaStructure, T extends ChannelTableNames<S>> =
12
+ | ChannelQuery<S, T>
13
+ | ReadonlyArray<ChannelQuery<S, T>>;
14
+
15
+ /** An open channel, for as long as the component lives. */
16
+ export interface UseChannel<S extends SchemaStructure, T extends string> {
17
+ /** `idle` | `connecting` | `connected` | `failed` | `unsupported`. */
18
+ status: () => ChannelStatus;
19
+ /** Users with a tab connected. */
20
+ peers: () => ReadonlyArray<string>;
21
+ /** Writes that go to THIS channel's peers only (when the row matches its query), plus the database as always. */
22
+ update: Sp00kyChannel<S, T>['update'];
23
+ create: Sp00kyChannel<S, T>['create'];
24
+ delete: Sp00kyChannel<S, T>['delete'];
25
+ }
26
+
27
+ const IDLE: ChannelState = { status: 'idle', peers: [] };
28
+
29
+ /**
30
+ * Open a peer to peer channel to `peers` for the rows `query` matches, for
31
+ * the lifetime of the component. The query must be on a `-- @channel` table
32
+ * and only its `where` counts; it is checked against each row, never
33
+ * registered. Writes to matching rows (`db.update` / `db.create` /
34
+ * `db.delete`, or the channel's own) reach the peers over WebRTC in tens of
35
+ * ms; `-- @ephemeral` fields travel only this way. A connection forms when
36
+ * both sides list each other; your own id is skipped.
37
+ *
38
+ * ```ts
39
+ * const ch = useChannel(
40
+ * () => db.query('message').where({ conversation: convoId() }),
41
+ * () => [me(), other()]
42
+ * );
43
+ * ```
44
+ *
45
+ * `query` may be an accessor (re-read when it changes; `null` closes the
46
+ * channel until it returns a query again) or a list of queries.
47
+ */
48
+ export function useChannel<S extends SchemaStructure, T extends ChannelTableNames<S>>(
49
+ query: ChannelQueries<S, T> | (() => ChannelQueries<S, T> | null | undefined),
50
+ peers: ChannelPeers
51
+ ): UseChannel<S, T> {
52
+ const db = useDb() as SyncedDb<any>;
53
+ const queries = query as ChannelQueries<any, any> | (() => ChannelQueries<any, any> | null | undefined);
54
+ const readQueries = () => (typeof queries === 'function' ? queries() : queries);
55
+ const readPeers = () => (typeof peers === 'function' ? (peers() ?? []) : peers);
56
+ const [state, setState] = createSignal<ChannelState>(IDLE, { ownedWrite: true });
57
+
58
+ let channel: Sp00kyChannel<any, any> | null = null;
59
+ let stop = () => {};
60
+ const close = () => {
61
+ stop();
62
+ channel?.close();
63
+ channel = null;
64
+ setState(IDLE);
65
+ };
66
+ const sync = (q: ChannelQueries<any, any> | null | undefined) => {
67
+ if (!q) return close();
68
+ if (channel) return channel.setQueries(q);
69
+ channel = (db as SyncedDb<any>).channel(q, untrack(readPeers));
70
+ stop = channel.subscribe(setState);
71
+ };
72
+ sync(untrack(readQueries));
73
+
74
+ // Two-arg Solid 2 effects: the compute tracks, the apply acts (its first
75
+ // run repeats what the channel was opened with, which is harmless).
76
+ if (typeof queries === 'function') createEffect(() => queries(), (q) => sync(q));
77
+ if (typeof peers === 'function') createEffect(() => [...readPeers()], (next) => channel?.setPeers(next));
78
+
79
+ onCleanup(close);
80
+
81
+ const open = () => {
82
+ if (!channel) throw new Error('This channel is closed (its query accessor returned nothing).');
83
+ return channel;
84
+ };
85
+ return {
86
+ status: () => state().status,
87
+ peers: () => state().peers,
88
+ update: ((...args: Parameters<Sp00kyChannel<any, any>['update']>) => open().update(...args)) as UseChannel<S, T>['update'],
89
+ create: ((...args: Parameters<Sp00kyChannel<any, any>['create']>) => open().create(...args)) as UseChannel<S, T>['create'],
90
+ delete: ((...args: Parameters<Sp00kyChannel<any, any>['delete']>) => open().delete(...args)) as UseChannel<S, T>['delete'],
91
+ };
92
+ }