@spooky-sync/client-solid2 0.0.1-canary.354 → 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/AGENTS.md +1 -0
- package/dist/index.cjs +72 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +47 -3
- package/dist/index.d.cts.map +1 -1
- package/dist/index.d.ts +47 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +73 -2
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
- package/skills/sp00ky-solid2/SKILL.md +18 -0
- package/src/index.ts +19 -0
- package/src/lib/__tests__/use-channel.types.test.ts +52 -0
- package/src/lib/use-channel.ts +92 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@spooky-sync/client-solid2",
|
|
3
|
-
"version": "0.0.1-canary.
|
|
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.
|
|
47
|
-
"@spooky-sync/core": "0.0.1-canary.
|
|
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
|
+
}
|