@syncular/react 0.7.0 → 0.8.0

package/README.md

@@ -164,6 +164,9 @@ not need a custom retention effect.
   means an inbound pull/catch-up signal.
 - `useConflicts()` observes conflicts and rejections only when that domain
   changes.
+- `useCommitOutcomes()` observes the durable newest-first final-outcome journal
+  from exact `outcomesChanged` batches. Resolve entries through
+  `useSyncClient().resolveCommitOutcome(...)`.
 - `usePresence(scopeKey)` observes ephemeral realtime peers.
 - `useSyncClient()` and `useReactiveStore()` expose the normalized low-level
   surfaces for integrations.

package/dist/client.d.ts

@@ -11,7 +11,7 @@
  * value → read it) and wraps every result in `Promise.resolve`, so a hook
  * never has to care which core it holds.
  */
-import type { ClientChangeListener, ConflictRecord, InvalidationListener, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, SchemaFloor, SqlRow, SqlValue, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
+import type { ClientChangeListener, CommitOutcome, CommitOutcomeQuery, ConflictRecord, InvalidationListener, LeaseState, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, ResolveCommitOutcomeInput, SchemaFloor, SqlRow, SqlValue, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
 /**
  * The structural union of `SyncClient` and `SyncClientHandle`. Members that
  * diverge are typed as "value or method, sync or promise"; {@link normalizeClient}
@@ -31,6 +31,9 @@ export interface SyncClientLike {
     statusSnapshot(): SyncStatusSnapshot | Promise<SyncStatusSnapshot>;
     conflicts: readonly ConflictRecord[] | (() => readonly ConflictRecord[] | Promise<readonly ConflictRecord[]>);
     rejections: readonly RejectionRecord[] | (() => readonly RejectionRecord[] | Promise<readonly RejectionRecord[]>);
+    commitOutcome(clientCommitId: string): CommitOutcome | undefined | Promise<CommitOutcome | undefined>;
+    commitOutcomes(query?: CommitOutcomeQuery): readonly CommitOutcome[] | Promise<readonly CommitOutcome[]>;
+    resolveCommitOutcome(input: ResolveCommitOutcomeInput): CommitOutcome | Promise<CommitOutcome>;
     schemaFloor: SchemaFloor | undefined | (() => SchemaFloor | undefined | Promise<SchemaFloor | undefined>);
     leaseState: LeaseState | undefined | (() => LeaseState | undefined | Promise<LeaseState | undefined>);
     upgrading: boolean | (() => boolean | Promise<boolean>);
@@ -57,6 +60,9 @@ export interface NormalizedClient {
     statusSnapshot(): Promise<SyncStatusSnapshot>;
     conflicts(): Promise<readonly ConflictRecord[]>;
     rejections(): Promise<readonly RejectionRecord[]>;
+    commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;
+    commitOutcomes(query?: CommitOutcomeQuery): Promise<readonly CommitOutcome[]>;
+    resolveCommitOutcome(input: ResolveCommitOutcomeInput): Promise<CommitOutcome>;
     schemaFloor(): Promise<SchemaFloor | undefined>;
     leaseState(): Promise<LeaseState | undefined>;
     upgrading(): Promise<boolean>;

package/dist/client.js

@@ -22,6 +22,9 @@ export function normalizeClient(client) {
         statusSnapshot: () => Promise.resolve(client.statusSnapshot()),
         conflicts: () => resolveMember(client, 'conflicts'),
         rejections: () => resolveMember(client, 'rejections'),
+        commitOutcome: (clientCommitId) => Promise.resolve(client.commitOutcome(clientCommitId)),
+        commitOutcomes: (query) => Promise.resolve(client.commitOutcomes(query)),
+        resolveCommitOutcome: (input) => Promise.resolve(client.resolveCommitOutcome(input)),
         schemaFloor: () => resolveMember(client, 'schemaFloor'),
         leaseState: () => resolveMember(client, 'leaseState'),
         upgrading: () => resolveMember(client, 'upgrading'),

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { inferTables } from './infer-tables.js';
 export { SyncContext, SyncProvider, type SyncProviderProps, SyncStoreContext, } from './provider.js';
 export { createSyncClientResource, isSyncClientResource, type SyncClientResource, type SyncClientResourceSnapshot, } from './resource.js';
 export { useReactiveStore, useSyncClient } from './use-client.js';
+export { type UseCommitOutcomesResult, useCommitOutcomes, } from './use-commit-outcomes.js';
 export { type UseConflictsResult, useConflicts } from './use-conflicts.js';
 export { type SyncTableDescriptor, type UseMutationOptions, type UseMutationResult, type UseTableMutationResult, useMutation, } from './use-mutation.js';
 export { usePresence } from './use-presence.js';

package/dist/index.js

@@ -6,6 +6,7 @@ export { inferTables } from './infer-tables.js';
 export { SyncContext, SyncProvider, SyncStoreContext, } from './provider.js';
 export { createSyncClientResource, isSyncClientResource, } from './resource.js';
 export { useReactiveStore, useSyncClient } from './use-client.js';
+export { useCommitOutcomes, } from './use-commit-outcomes.js';
 export { useConflicts } from './use-conflicts.js';
 export { useMutation, } from './use-mutation.js';
 export { usePresence } from './use-presence.js';

package/dist/use-commit-outcomes.d.ts

@@ -0,0 +1,12 @@
+import type { CommitOutcome } from '@syncular/client';
+export interface UseCommitOutcomesResult {
+    readonly outcomes: readonly CommitOutcome[];
+    readonly isLoading: boolean;
+    readonly error: Error | undefined;
+    readonly refresh: () => void;
+}
+/**
+ * Durable newest-first commit history. It updates from the exact
+ * `outcomesChanged` transaction event, including resolution transitions.
+ */
+export declare function useCommitOutcomes(): UseCommitOutcomesResult;

package/dist/use-commit-outcomes.js

@@ -0,0 +1,17 @@
+import { useCallback, useSyncExternalStore } from 'react';
+import { useReactiveStore } from './use-client.js';
+/**
+ * Durable newest-first commit history. It updates from the exact
+ * `outcomesChanged` transaction event, including resolution transitions.
+ */
+export function useCommitOutcomes() {
+    const entry = useReactiveStore().outcomes;
+    const snapshot = useSyncExternalStore(entry.subscribe, entry.getSnapshot, entry.getSnapshot);
+    const refresh = useCallback(() => entry.refresh(), [entry]);
+    return {
+        outcomes: snapshot.outcomes,
+        isLoading: snapshot.isLoading,
+        error: snapshot.error,
+        refresh,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/react",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "React hooks for Syncular offline-first sync",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -48,15 +48,15 @@
     "test": "bun test --preload ./test/setup.ts"
   },
   "dependencies": {
-    "@syncular/client": "0.7.0"
+    "@syncular/client": "0.8.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^15.11.0",
-    "@syncular/core": "0.7.0",
-    "@syncular/server": "0.7.0",
+    "@syncular/core": "0.8.0",
+    "@syncular/server": "0.8.0",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^18.3.0",
     "react": "^18.3.1",

package/src/client.ts

@@ -13,6 +13,8 @@
  */
 import type {
   ClientChangeListener,
+  CommitOutcome,
+  CommitOutcomeQuery,
   ConflictRecord,
   InvalidationListener,
   LeaseState,
@@ -21,6 +23,7 @@ import type {
   QueryReadSpec,
   QuerySnapshot,
   RejectionRecord,
+  ResolveCommitOutcomeInput,
   SchemaFloor,
   SqlRow,
   SqlValue,
@@ -60,6 +63,15 @@ export interface SyncClientLike {
   rejections:
     | readonly RejectionRecord[]
     | (() => readonly RejectionRecord[] | Promise<readonly RejectionRecord[]>);
+  commitOutcome(
+    clientCommitId: string,
+  ): CommitOutcome | undefined | Promise<CommitOutcome | undefined>;
+  commitOutcomes(
+    query?: CommitOutcomeQuery,
+  ): readonly CommitOutcome[] | Promise<readonly CommitOutcome[]>;
+  resolveCommitOutcome(
+    input: ResolveCommitOutcomeInput,
+  ): CommitOutcome | Promise<CommitOutcome>;
   schemaFloor:
     | SchemaFloor
     | undefined
@@ -118,6 +130,11 @@ export interface NormalizedClient {
   statusSnapshot(): Promise<SyncStatusSnapshot>;
   conflicts(): Promise<readonly ConflictRecord[]>;
   rejections(): Promise<readonly RejectionRecord[]>;
+  commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;
+  commitOutcomes(query?: CommitOutcomeQuery): Promise<readonly CommitOutcome[]>;
+  resolveCommitOutcome(
+    input: ResolveCommitOutcomeInput,
+  ): Promise<CommitOutcome>;
   schemaFloor(): Promise<SchemaFloor | undefined>;
   leaseState(): Promise<LeaseState | undefined>;
   upgrading(): Promise<boolean>;
@@ -145,6 +162,11 @@ export function normalizeClient(client: SyncClientLike): NormalizedClient {
     statusSnapshot: () => Promise.resolve(client.statusSnapshot()),
     conflicts: () => resolveMember(client, 'conflicts'),
     rejections: () => resolveMember(client, 'rejections'),
+    commitOutcome: (clientCommitId) =>
+      Promise.resolve(client.commitOutcome(clientCommitId)),
+    commitOutcomes: (query) => Promise.resolve(client.commitOutcomes(query)),
+    resolveCommitOutcome: (input) =>
+      Promise.resolve(client.resolveCommitOutcome(input)),
     schemaFloor: () => resolveMember(client, 'schemaFloor'),
     leaseState: () => resolveMember(client, 'leaseState'),
     upgrading: () => resolveMember(client, 'upgrading'),

package/src/index.ts

@@ -29,6 +29,10 @@ export {
   type SyncClientResourceSnapshot,
 } from './resource';
 export { useReactiveStore, useSyncClient } from './use-client';
+export {
+  type UseCommitOutcomesResult,
+  useCommitOutcomes,
+} from './use-commit-outcomes';
 export { type UseConflictsResult, useConflicts } from './use-conflicts';
 export {
   type SyncTableDescriptor,

package/src/use-commit-outcomes.ts

@@ -0,0 +1,30 @@
+import type { CommitOutcome } from '@syncular/client';
+import { useCallback, useSyncExternalStore } from 'react';
+import { useReactiveStore } from './use-client';
+
+export interface UseCommitOutcomesResult {
+  readonly outcomes: readonly CommitOutcome[];
+  readonly isLoading: boolean;
+  readonly error: Error | undefined;
+  readonly refresh: () => void;
+}
+
+/**
+ * Durable newest-first commit history. It updates from the exact
+ * `outcomesChanged` transaction event, including resolution transitions.
+ */
+export function useCommitOutcomes(): UseCommitOutcomesResult {
+  const entry = useReactiveStore().outcomes;
+  const snapshot = useSyncExternalStore(
+    entry.subscribe,
+    entry.getSnapshot,
+    entry.getSnapshot,
+  );
+  const refresh = useCallback(() => entry.refresh(), [entry]);
+  return {
+    outcomes: snapshot.outcomes,
+    isLoading: snapshot.isLoading,
+    error: snapshot.error,
+    refresh,
+  };
+}