@syncular/react 0.57.0 → 0.59.0

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/README.md CHANGED
@@ -27,7 +27,7 @@ function Tasks({ projectId }: { projectId: string }) {
27
27
  const mutation = useMutation(tasksTable);
28
28
 
29
29
  if (tasks.phase === 'loading') return <p>Loading…</p>;
30
- if (tasks.phase === 'blocked') {
30
+ if (tasks.phase === 'blocked' && tasks.availability.state === 'blocked') {
31
31
  return <p>Sync unavailable: {tasks.availability.reason}</p>;
32
32
  }
33
33
  if (tasks.phase === 'error') return <p>{tasks.error?.message}</p>;
@@ -62,12 +62,16 @@ availability, refresh }`. `availability` is the typed `ready`, `migrating`, or
62
62
  - `partial`: rows exist, but some required window coverage is incomplete;
63
63
  - `ready`: the atomic snapshot says the answer is complete, including an
64
64
  honestly empty result;
65
- - `blocked`: sync cannot safely serve a fresh result because the generated
66
- schema is incompatible or the browser leader is unreachable. `isLoading`
67
- is `false`; previously read rows remain available for deliberate read-only
68
- UI, and `availability.reason` identifies the boundary;
65
+ - `blocked`: the tab cannot read through the browser leader, and
66
+ `availability.reason` is `leader-unreachable`, `leader-incompatible`, or
67
+ `leadership-taken`. `isLoading` is `false`; previously read rows remain
68
+ available for deliberate read-only UI. A schema block stops network transfer
69
+ and leaves local reads running, so it appears in `availability` and leaves
70
+ `phase` unchanged;
69
71
  - `error`: the latest read failed. A refresh error keeps the rows and revision
70
72
  from the last successful read while setting `isRefreshing` to `false`.
73
+ - `disabled`: the hook was given `enabled: false` and reads nothing; `rows`
74
+ is empty and `isLoading` is `false`.
71
75
 
72
76
  ## Provider and async initialization
73
77
 
@@ -219,9 +223,11 @@ Options:
219
223
  | `id` | Stable cache identity for a raw query. |
220
224
  | `tables`, `scopeKeys` | Compatibility shorthand; prefer `dependencies`. |
221
225
 
222
- Without explicit dependencies, raw SQL uses a conservative `FROM`/`JOIN`
223
- scan. Generated queries are preferred whenever the statement is known at
224
- build time because typegen can prove more.
226
+ `useRawSql` reads no table names from the SQL text. Pass `dependencies` or
227
+ `tables` naming every table the statement reads; without either, the hook
228
+ throws a `ClientSyncError` with code `client.raw_sql_dependencies_required`
229
+ when it mounts. Generated queries are preferred whenever the statement is
230
+ known at build time because typegen derives the dependencies from the schema.
225
231
 
226
232
  ## Exact changes and windows
227
233
 
package/dist/index.d.ts CHANGED
@@ -8,7 +8,6 @@
8
8
  * option.
9
9
  */
10
10
  export type { SyncClientLike } from './client.js';
11
- export { inferTables } from './infer-tables.js';
12
11
  export { type SyncBoundaryActions, type SyncBoundaryState, SyncContext, SyncProvider, type SyncProviderProps, SyncStoreContext, } from './provider.js';
13
12
  export { createSyncClientResource, isSyncClientResource, type SyncClientResource, type SyncClientResourceSnapshot, } from './resource.js';
14
13
  export { SYNCULAR_REACT_RUNTIME_VERSION } from './runtime-version.js';
package/dist/index.js CHANGED
@@ -1,4 +1,3 @@
1
- export { inferTables } from './infer-tables.js';
2
1
  export { SyncContext, SyncProvider, SyncStoreContext, } from './provider.js';
3
2
  export { createSyncClientResource, isSyncClientResource, } from './resource.js';
4
3
  export { SYNCULAR_REACT_RUNTIME_VERSION } from './runtime-version.js';
@@ -3,4 +3,4 @@
3
3
  * Vite HMR uses it to replace a worker owner after a Syncular package upgrade
4
4
  * even when the application's generated schema version did not change.
5
5
  */
6
- export declare const SYNCULAR_REACT_RUNTIME_VERSION = "0.57.0";
6
+ export declare const SYNCULAR_REACT_RUNTIME_VERSION = "0.59.0";
@@ -3,4 +3,4 @@
3
3
  * Vite HMR uses it to replace a worker owner after a Syncular package upgrade
4
4
  * even when the application's generated schema version did not change.
5
5
  */
6
- export const SYNCULAR_REACT_RUNTIME_VERSION = '0.57.0';
6
+ export const SYNCULAR_REACT_RUNTIME_VERSION = '0.59.0';
@@ -1,4 +1,4 @@
1
- import { useCallback, useRef, useState } from 'react';
1
+ import { useCallback, useMemo, useRef, useState } from 'react';
2
2
  import { useSyncClient } from './use-client.js';
3
3
  export function useMutation(tableOrOptions, maybeOptions) {
4
4
  const client = useSyncClient();
@@ -39,36 +39,26 @@ export function useMutation(tableOrOptions, maybeOptions) {
39
39
  error,
40
40
  resetError,
41
41
  };
42
- const upsert = useCallback((values, baseVersion) => {
43
- if (table === undefined)
44
- throw new Error('table mutation descriptor missing');
45
- return mutate([
46
- {
47
- table: table.name,
48
- op: 'upsert',
49
- values: values,
50
- ...(baseVersion !== undefined ? { baseVersion } : {}),
51
- },
52
- ]);
53
- }, [mutate, table]);
54
- const patch = useCallback((id, partial, baseVersion) => {
55
- if (table === undefined)
56
- throw new Error('table mutation descriptor missing');
57
- return run(() => client.patch(table.name, String(id), partial, baseVersion !== undefined ? { baseVersion } : undefined));
58
- }, [client, run, table]);
59
- const remove = useCallback((id, baseVersion) => {
60
- if (table === undefined)
61
- throw new Error('table mutation descriptor missing');
62
- return mutate([
63
- {
64
- table: table.name,
65
- op: 'delete',
66
- rowId: String(id),
67
- ...(baseVersion !== undefined ? { baseVersion } : {}),
68
- },
69
- ]);
70
- }, [mutate, table]);
71
- if (table === undefined)
72
- return base;
73
- return { ...base, upsert, patch, remove };
42
+ const helpers = useMemo(() => table === undefined
43
+ ? undefined
44
+ : {
45
+ upsert: (values, baseVersion) => mutate([
46
+ {
47
+ table: table.name,
48
+ op: 'upsert',
49
+ values: values,
50
+ ...(baseVersion !== undefined ? { baseVersion } : {}),
51
+ },
52
+ ]),
53
+ patch: (id, partial, baseVersion) => run(() => client.patch(table.name, String(id), partial, baseVersion !== undefined ? { baseVersion } : undefined)),
54
+ remove: (id, baseVersion) => mutate([
55
+ {
56
+ table: table.name,
57
+ op: 'delete',
58
+ rowId: String(id),
59
+ ...(baseVersion !== undefined ? { baseVersion } : {}),
60
+ },
61
+ ]),
62
+ }, [client, mutate, run, table]);
63
+ return helpers === undefined ? base : { ...base, ...helpers };
74
64
  }
@@ -21,7 +21,8 @@ export interface UseRawSqlOptions<Row = SqlRow> {
21
21
  }
22
22
  export interface UseRawSqlResult<Row> {
23
23
  readonly rows: readonly Row[];
24
- readonly phase: LiveQueryPhase;
24
+ /** `disabled` while `enabled` is `false`: the hook reads nothing. */
25
+ readonly phase: LiveQueryPhase | 'disabled';
25
26
  readonly revision: bigint | undefined;
26
27
  readonly isLoading: boolean;
27
28
  readonly isRefreshing: boolean;
@@ -1,10 +1,9 @@
1
- import { canonicalValue, } from '@syncular/client';
1
+ import { canonicalValue, ClientSyncError, } from '@syncular/client';
2
2
  import { useCallback, useMemo, useSyncExternalStore } from 'react';
3
- import { inferTables } from './infer-tables.js';
4
3
  import { useReactiveStore } from './use-client.js';
5
4
  const DISABLED = {
6
5
  rows: [],
7
- phase: 'ready',
6
+ phase: 'disabled',
8
7
  revision: undefined,
9
8
  error: undefined,
10
9
  isRefreshing: false,
@@ -14,20 +13,24 @@ const noSubscribe = () => () => { };
14
13
  export function useRawSql(sql, params, options) {
15
14
  const store = useReactiveStore();
16
15
  const enabled = options?.enabled ?? true;
17
- const inferred = options?.tables ?? [...inferTables(sql)];
18
16
  const dependencies = options?.dependencies ??
19
- inferred.map((table) => ({
17
+ options?.tables?.map((table) => ({
20
18
  table,
21
19
  ...(options?.scopeKeys !== undefined
22
20
  ? { scopeKeys: options.scopeKeys }
23
21
  : {}),
24
22
  }));
23
+ if (dependencies === undefined) {
24
+ throw new ClientSyncError('client.raw_sql_dependencies_required', '@syncular/react: useRawSql needs `dependencies` or `tables` naming every table the SQL reads; the query re-runs only when one of them changes.');
25
+ }
25
26
  const coverage = options?.coverage ?? [];
27
+ const claimCoverage = options?.claimCoverage ?? true;
26
28
  const identity = canonicalValue({
27
29
  sql,
28
30
  params: params ?? [],
29
31
  dependencies,
30
32
  coverage,
33
+ claimCoverage,
31
34
  ...(options?.id !== undefined ? { id: options.id } : {}),
32
35
  });
33
36
  // `identity` canonically contains every value-shaped input. Depending on
@@ -44,7 +47,7 @@ export function useRawSql(sql, params, options) {
44
47
  ...(coverage.length > 0 ? { coverage } : {}),
45
48
  ...(options?.mapRow !== undefined ? { mapRow: options.mapRow } : {}),
46
49
  ...(options?.rowKey !== undefined ? { rowKey: options.rowKey } : {}),
47
- claimCoverage: options?.claimCoverage ?? true,
50
+ claimCoverage,
48
51
  }), [store, identity, options?.mapRow, options?.rowKey]);
49
52
  // oxlint-enable react-hooks/exhaustive-deps
50
53
  const snapshot = useSyncExternalStore(enabled ? entry.subscribe : noSubscribe, enabled ? entry.getSnapshot : () => DISABLED, enabled ? entry.getSnapshot : () => DISABLED);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/react",
3
- "version": "0.57.0",
3
+ "version": "0.59.0",
4
4
  "description": "React hooks for Syncular offline-first sync",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -55,15 +55,15 @@
55
55
  "test": "bun test --preload ./test/setup.ts"
56
56
  },
57
57
  "dependencies": {
58
- "@syncular/client": "0.57.0"
58
+ "@syncular/client": "0.59.0"
59
59
  },
60
60
  "peerDependencies": {
61
61
  "react": ">=18.0.0"
62
62
  },
63
63
  "devDependencies": {
64
64
  "@happy-dom/global-registrator": "^20.0.0",
65
- "@syncular/core": "0.57.0",
66
- "@syncular/server": "0.57.0",
65
+ "@syncular/core": "0.59.0",
66
+ "@syncular/server": "0.59.0",
67
67
  "@testing-library/react": "^16.1.0",
68
68
  "@types/react": "^18.3.0",
69
69
  "@types/react-dom": "^18.3.0",
package/src/index.ts CHANGED
@@ -8,7 +8,6 @@
8
8
  * option.
9
9
  */
10
10
  export type { SyncClientLike } from './client';
11
- export { inferTables } from './infer-tables';
12
11
  export {
13
12
  type SyncBoundaryActions,
14
13
  type SyncBoundaryState,
@@ -3,4 +3,4 @@
3
3
  * Vite HMR uses it to replace a worker owner after a Syncular package upgrade
4
4
  * even when the application's generated schema version did not change.
5
5
  */
6
- export const SYNCULAR_REACT_RUNTIME_VERSION = '0.57.0';
6
+ export const SYNCULAR_REACT_RUNTIME_VERSION = '0.59.0';
@@ -1,5 +1,5 @@
1
1
  import type { MutationInput } from '@syncular/client';
2
- import { useCallback, useRef, useState } from 'react';
2
+ import { useCallback, useMemo, useRef, useState } from 'react';
3
3
  import { useSyncClient } from './use-client';
4
4
 
5
5
  export interface SyncTableDescriptor<Row, Insert, Update, Id> {
@@ -99,55 +99,40 @@ export function useMutation<Row, Insert, Update, Id>(
99
99
  error,
100
100
  resetError,
101
101
  };
102
- const upsert = useCallback(
103
- (values: Insert, baseVersion?: number): Promise<string> => {
104
- if (table === undefined)
105
- throw new Error('table mutation descriptor missing');
106
- return mutate([
107
- {
108
- table: table.name,
109
- op: 'upsert',
110
- values: values as Readonly<Record<string, unknown>>,
111
- ...(baseVersion !== undefined ? { baseVersion } : {}),
112
- },
113
- ]);
114
- },
115
- [mutate, table],
116
- );
117
- const patch = useCallback(
118
- (
119
- id: Id,
120
- partial: Partial<Update>,
121
- baseVersion?: number,
122
- ): Promise<string> => {
123
- if (table === undefined)
124
- throw new Error('table mutation descriptor missing');
125
- return run(() =>
126
- client.patch(
127
- table.name,
128
- String(id),
129
- partial as Readonly<Record<string, unknown>>,
130
- baseVersion !== undefined ? { baseVersion } : undefined,
131
- ),
132
- );
133
- },
134
- [client, run, table],
135
- );
136
- const remove = useCallback(
137
- (id: Id, baseVersion?: number): Promise<string> => {
138
- if (table === undefined)
139
- throw new Error('table mutation descriptor missing');
140
- return mutate([
141
- {
142
- table: table.name,
143
- op: 'delete',
144
- rowId: String(id),
145
- ...(baseVersion !== undefined ? { baseVersion } : {}),
146
- },
147
- ]);
148
- },
149
- [mutate, table],
102
+ const helpers = useMemo(
103
+ () =>
104
+ table === undefined
105
+ ? undefined
106
+ : {
107
+ upsert: (values: Insert, baseVersion?: number) =>
108
+ mutate([
109
+ {
110
+ table: table.name,
111
+ op: 'upsert',
112
+ values: values as Readonly<Record<string, unknown>>,
113
+ ...(baseVersion !== undefined ? { baseVersion } : {}),
114
+ },
115
+ ]),
116
+ patch: (id: Id, partial: Partial<Update>, baseVersion?: number) =>
117
+ run(() =>
118
+ client.patch(
119
+ table.name,
120
+ String(id),
121
+ partial as Readonly<Record<string, unknown>>,
122
+ baseVersion !== undefined ? { baseVersion } : undefined,
123
+ ),
124
+ ),
125
+ remove: (id: Id, baseVersion?: number) =>
126
+ mutate([
127
+ {
128
+ table: table.name,
129
+ op: 'delete',
130
+ rowId: String(id),
131
+ ...(baseVersion !== undefined ? { baseVersion } : {}),
132
+ },
133
+ ]),
134
+ },
135
+ [client, mutate, run, table],
150
136
  );
151
- if (table === undefined) return base;
152
- return { ...base, upsert, patch, remove };
137
+ return helpers === undefined ? base : { ...base, ...helpers };
153
138
  }
@@ -1,6 +1,8 @@
1
1
  import {
2
2
  canonicalValue,
3
+ ClientSyncError,
3
4
  type LiveQueryPhase,
5
+ type LiveQueryResult,
4
6
  type QueryDependency,
5
7
  type SqlRow,
6
8
  type SqlValue,
@@ -8,7 +10,6 @@ import {
8
10
  type WindowCoverage,
9
11
  } from '@syncular/client';
10
12
  import { useCallback, useMemo, useSyncExternalStore } from 'react';
11
- import { inferTables } from './infer-tables';
12
13
  import { useReactiveStore } from './use-client';
13
14
 
14
15
  export interface UseRawSqlOptions<Row = SqlRow> {
@@ -34,7 +35,8 @@ export interface UseRawSqlOptions<Row = SqlRow> {
34
35
 
35
36
  export interface UseRawSqlResult<Row> {
36
37
  readonly rows: readonly Row[];
37
- readonly phase: LiveQueryPhase;
38
+ /** `disabled` while `enabled` is `false`: the hook reads nothing. */
39
+ readonly phase: LiveQueryPhase | 'disabled';
38
40
  readonly revision: bigint | undefined;
39
41
  readonly isLoading: boolean;
40
42
  readonly isRefreshing: boolean;
@@ -45,7 +47,7 @@ export interface UseRawSqlResult<Row> {
45
47
 
46
48
  const DISABLED = {
47
49
  rows: [],
48
- phase: 'ready',
50
+ phase: 'disabled',
49
51
  revision: undefined,
50
52
  error: undefined,
51
53
  isRefreshing: false,
@@ -61,21 +63,28 @@ export function useRawSql<Row = SqlRow>(
61
63
  ): UseRawSqlResult<Row> {
62
64
  const store = useReactiveStore();
63
65
  const enabled = options?.enabled ?? true;
64
- const inferred = options?.tables ?? [...inferTables(sql)];
65
66
  const dependencies =
66
67
  options?.dependencies ??
67
- inferred.map((table) => ({
68
+ options?.tables?.map((table) => ({
68
69
  table,
69
70
  ...(options?.scopeKeys !== undefined
70
71
  ? { scopeKeys: options.scopeKeys }
71
72
  : {}),
72
73
  }));
74
+ if (dependencies === undefined) {
75
+ throw new ClientSyncError(
76
+ 'client.raw_sql_dependencies_required',
77
+ '@syncular/react: useRawSql needs `dependencies` or `tables` naming every table the SQL reads; the query re-runs only when one of them changes.',
78
+ );
79
+ }
73
80
  const coverage = options?.coverage ?? [];
81
+ const claimCoverage = options?.claimCoverage ?? true;
74
82
  const identity = canonicalValue({
75
83
  sql,
76
84
  params: params ?? [],
77
85
  dependencies,
78
86
  coverage,
87
+ claimCoverage,
79
88
  ...(options?.id !== undefined ? { id: options.id } : {}),
80
89
  });
81
90
  // `identity` canonically contains every value-shaped input. Depending on
@@ -94,12 +103,12 @@ export function useRawSql<Row = SqlRow>(
94
103
  ...(coverage.length > 0 ? { coverage } : {}),
95
104
  ...(options?.mapRow !== undefined ? { mapRow: options.mapRow } : {}),
96
105
  ...(options?.rowKey !== undefined ? { rowKey: options.rowKey } : {}),
97
- claimCoverage: options?.claimCoverage ?? true,
106
+ claimCoverage,
98
107
  }),
99
108
  [store, identity, options?.mapRow, options?.rowKey],
100
109
  );
101
110
  // oxlint-enable react-hooks/exhaustive-deps
102
- const snapshot = useSyncExternalStore(
111
+ const snapshot = useSyncExternalStore<LiveQueryResult<Row> | typeof DISABLED>(
103
112
  enabled ? entry.subscribe : noSubscribe,
104
113
  enabled ? entry.getSnapshot : () => DISABLED,
105
114
  enabled ? entry.getSnapshot : () => DISABLED,
@@ -1,20 +0,0 @@
1
- /**
2
- * Conservative table inference for `useRawSql`: infer
3
- * conservatively from the SQL text's table names … documented as a
4
- * heuristic with the explicit option as the escape hatch").
5
- *
6
- * This is a SIMPLE identifier scan, NOT a SQL parser. It collects the
7
- * identifiers that follow `FROM` and `JOIN` — the tables a SELECT reads.
8
- * It is deliberately over-inclusive at the edges (a table aliased in a CTE,
9
- * a function-table, an odd quoting style) because the failure mode of
10
- * over-inclusion is a harmless extra re-run, whereas under-inclusion is a
11
- * stale query — the one thing live queries must never do. When a query's
12
- * real dependencies cannot be read off its text (dynamic SQL, views,
13
- * unusual syntax), pass the explicit `tables` option; that always wins.
14
- */
15
- /**
16
- * Extract the table names a SELECT reads. Returns a de-duplicated,
17
- * lower-nothing set (identifiers are compared to invalidation table names
18
- * as-is — SQLite table names are case-sensitive for our generated schema).
19
- */
20
- export declare function inferTables(sql: string): Set<string>;
@@ -1,33 +0,0 @@
1
- /**
2
- * Conservative table inference for `useRawSql`: infer
3
- * conservatively from the SQL text's table names … documented as a
4
- * heuristic with the explicit option as the escape hatch").
5
- *
6
- * This is a SIMPLE identifier scan, NOT a SQL parser. It collects the
7
- * identifiers that follow `FROM` and `JOIN` — the tables a SELECT reads.
8
- * It is deliberately over-inclusive at the edges (a table aliased in a CTE,
9
- * a function-table, an odd quoting style) because the failure mode of
10
- * over-inclusion is a harmless extra re-run, whereas under-inclusion is a
11
- * stale query — the one thing live queries must never do. When a query's
12
- * real dependencies cannot be read off its text (dynamic SQL, views,
13
- * unusual syntax), pass the explicit `tables` option; that always wins.
14
- */
15
- const FROM_JOIN_RE = /\b(?:from|join)\s+(?:"([^"]+)"|`([^`]+)`|\[([^\]]+)\]|([a-zA-Z_][a-zA-Z0-9_$]*))/gi;
16
- /**
17
- * Extract the table names a SELECT reads. Returns a de-duplicated,
18
- * lower-nothing set (identifiers are compared to invalidation table names
19
- * as-is — SQLite table names are case-sensitive for our generated schema).
20
- */
21
- export function inferTables(sql) {
22
- const tables = new Set();
23
- // Strip a leading schema qualifier (`main.tasks` → `tasks`) so the name
24
- // matches the invalidation event's bare table name.
25
- for (const match of sql.matchAll(FROM_JOIN_RE)) {
26
- const raw = match[1] ?? match[2] ?? match[3] ?? match[4];
27
- if (raw === undefined)
28
- continue;
29
- const dot = raw.lastIndexOf('.');
30
- tables.add(dot === -1 ? raw : raw.slice(dot + 1));
31
- }
32
- return tables;
33
- }
@@ -1,35 +0,0 @@
1
- /**
2
- * Conservative table inference for `useRawSql`: infer
3
- * conservatively from the SQL text's table names … documented as a
4
- * heuristic with the explicit option as the escape hatch").
5
- *
6
- * This is a SIMPLE identifier scan, NOT a SQL parser. It collects the
7
- * identifiers that follow `FROM` and `JOIN` — the tables a SELECT reads.
8
- * It is deliberately over-inclusive at the edges (a table aliased in a CTE,
9
- * a function-table, an odd quoting style) because the failure mode of
10
- * over-inclusion is a harmless extra re-run, whereas under-inclusion is a
11
- * stale query — the one thing live queries must never do. When a query's
12
- * real dependencies cannot be read off its text (dynamic SQL, views,
13
- * unusual syntax), pass the explicit `tables` option; that always wins.
14
- */
15
-
16
- const FROM_JOIN_RE =
17
- /\b(?:from|join)\s+(?:"([^"]+)"|`([^`]+)`|\[([^\]]+)\]|([a-zA-Z_][a-zA-Z0-9_$]*))/gi;
18
-
19
- /**
20
- * Extract the table names a SELECT reads. Returns a de-duplicated,
21
- * lower-nothing set (identifiers are compared to invalidation table names
22
- * as-is — SQLite table names are case-sensitive for our generated schema).
23
- */
24
- export function inferTables(sql: string): Set<string> {
25
- const tables = new Set<string>();
26
- // Strip a leading schema qualifier (`main.tasks` → `tasks`) so the name
27
- // matches the invalidation event's bare table name.
28
- for (const match of sql.matchAll(FROM_JOIN_RE)) {
29
- const raw = match[1] ?? match[2] ?? match[3] ?? match[4];
30
- if (raw === undefined) continue;
31
- const dot = raw.lastIndexOf('.');
32
- tables.add(dot === -1 ? raw : raw.slice(dot + 1));
33
- }
34
- return tables;
35
- }