on-zero 0.4.13 → 0.4.14

package/src/helpers/useMutation.test.ts

@@ -0,0 +1,117 @@
+import { afterEach, describe, expect, test, vi } from 'vitest'
+
+import { observeMutation, onMutationError, type MutationError } from './useMutation'
+
+// a controllable stand-in for Zero's MutatorResult { client, server }.
+function deferred<T>() {
+  let resolve!: (v: T) => void
+  let reject!: (e: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+function fakeResult() {
+  const client = deferred<unknown>()
+  const server = deferred<unknown>()
+  return {
+    result: { client: client.promise, server: server.promise },
+    client,
+    server,
+  }
+}
+
+const SUCCESS = { type: 'success' as const }
+const appError = (message: string) => ({
+  type: 'error' as const,
+  error: { type: 'app' as const, message },
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('observeMutation', () => {
+  test('success on both phases reports nothing', async () => {
+    const { result, client, server } = fakeResult()
+    const errors: MutationError[] = []
+    const dispose = onMutationError((e) => errors.push(e))
+
+    const done = observeMutation(result, (e) => errors.push(e))
+    client.resolve(SUCCESS)
+    server.resolve(SUCCESS)
+    await done
+
+    expect(errors).toEqual([])
+    dispose()
+  })
+
+  test('a server rejection surfaces a normalized error locally and globally', async () => {
+    const { result, client, server } = fakeResult()
+    const local: MutationError[] = []
+    const global: MutationError[] = []
+    const dispose = onMutationError((e) => global.push(e))
+
+    const done = observeMutation(result, (e) => local.push(e))
+    // optimistic phase succeeds, authoritative phase is rejected by the server
+    client.resolve(SUCCESS)
+    server.resolve(appError('Could not create post.'))
+    await done
+
+    expect(local).toEqual([
+      { scope: 'server', kind: 'app', message: 'Could not create post.', details: undefined },
+    ])
+    expect(global).toEqual(local)
+    dispose()
+  })
+
+  test('client + server both failing emits to the global catch only once', async () => {
+    const { result, client, server } = fakeResult()
+    const global: MutationError[] = []
+    const dispose = onMutationError((e) => global.push(e))
+
+    // a thrown optimistic mutator rejects both phases
+    const done = observeMutation(result)
+    client.reject(new Error('boom'))
+    server.reject(new Error('boom'))
+    await done
+
+    expect(global).toHaveLength(1)
+    expect(global[0]).toMatchObject({ scope: 'client', kind: 'zero', message: 'boom' })
+    dispose()
+  })
+
+  test('never rejects even when both phases reject', async () => {
+    const { result, client, server } = fakeResult()
+    client.reject(new Error('x'))
+    server.reject(new Error('x'))
+    await expect(observeMutation(result)).resolves.toBeUndefined()
+  })
+
+  test('with no listener registered it falls back to console.error in dev', async () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { result, client, server } = fakeResult()
+    const done = observeMutation(result)
+    client.resolve(SUCCESS)
+    server.resolve(appError('denied'))
+    await done
+    expect(spy).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('onMutationError', () => {
+  test('dispose stops delivery', async () => {
+    const seen: MutationError[] = []
+    const dispose = onMutationError((e) => seen.push(e))
+    dispose()
+
+    const { result, client, server } = fakeResult()
+    const done = observeMutation(result)
+    client.resolve(SUCCESS)
+    server.resolve(appError('denied'))
+    await done
+    expect(seen).toEqual([])
+  })
+})

package/src/helpers/useMutation.tsx

@@ -0,0 +1,170 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+// a Zero mutator call returns this — two promises for the optimistic-local and
+// the authoritative-server phases. we never make callers await either one.
+type MutatorResultLike = {
+  client: Promise<unknown>
+  server: Promise<unknown>
+}
+
+// normalized error from either phase. `scope` says which run failed:
+//   - 'client': the optimistic mutator threw locally (basically a real bug)
+//   - 'server': the authoritative run rejected (permission/validation) and Zero
+//     rolled the optimistic write back
+// `kind` mirrors Zero's MutatorResultDetails error.type ('app' | 'zero').
+export type MutationError = {
+  scope: 'client' | 'server'
+  kind: 'app' | 'zero'
+  message: string
+  details?: unknown
+}
+
+export type MutationState = {
+  // a server round-trip from the latest call is in flight. only for guarding a
+  // re-submit or a subtle "saving" affordance — never gate the rendered result
+  // on this, the optimistic store already updated the UI.
+  pending: boolean
+  // latest-call error (client or server), or null. render it inline.
+  error: MutationError | null
+  reset: () => void
+}
+
+// global catch so a fire-and-forget mutation can never silently swallow a server
+// rejection. apps register a handler (toast/log); with none registered we still
+// surface in dev so a swallowed error is impossible.
+const mutationErrorListeners = new Set<(error: MutationError) => void>()
+
+export function onMutationError(cb: (error: MutationError) => void): () => void {
+  mutationErrorListeners.add(cb)
+  return () => {
+    mutationErrorListeners.delete(cb)
+  }
+}
+
+function emitMutationError(error: MutationError): void {
+  if (mutationErrorListeners.size === 0) {
+    if (process.env.NODE_ENV !== 'production') {
+      console.error('[on-zero] unhandled mutation error', error)
+    }
+    return
+  }
+  for (const cb of mutationErrorListeners) cb(error)
+}
+
+function toMutationError(
+  scope: 'client' | 'server',
+  details: unknown,
+): MutationError | null {
+  if (!details || typeof details !== 'object') return null
+  const d = details as {
+    type?: string
+    error?: { type?: string; message?: string; details?: unknown }
+  }
+  if (d.type !== 'error') return null
+  return {
+    scope,
+    kind: d.error?.type === 'app' ? 'app' : 'zero',
+    message: d.error?.message || 'Mutation failed',
+    details: d.error?.details,
+  }
+}
+
+function rejectionToError(scope: 'client' | 'server', e: unknown): MutationError {
+  return {
+    scope,
+    kind: 'zero',
+    message: e instanceof Error ? e.message : String(e),
+  }
+}
+
+/**
+ * Wire a mutation result's optimistic-client and authoritative-server phases to
+ * normalized errors, without awaiting either. Every error reaches the global
+ * `onMutationError` catch (deduped — client and server can surface the same
+ * failure); an optional `onError` sink receives them too (the hook uses it for
+ * local state). Use this directly for a fire-and-forget call outside React:
+ *
+ *   observeMutation(zero.mutate.post.delete({ id }))
+ *
+ * Resolves once both phases settle. Never rejects.
+ */
+export function observeMutation(
+  result: MutatorResultLike,
+  onError?: (error: MutationError) => void,
+): Promise<void> {
+  let reportedGlobal = false
+  const report = (err: MutationError | null) => {
+    if (!err) return
+    onError?.(err)
+    // first error per call reaches the global catch
+    if (!reportedGlobal) {
+      reportedGlobal = true
+      emitMutationError(err)
+    }
+  }
+  const client = result.client
+    .then((d) => report(toMutationError('client', d)))
+    .catch((e) => report(rejectionToError('client', e)))
+  const server = result.server
+    .then((d) => report(toMutationError('server', d)))
+    .catch((e) => report(rejectionToError('server', e)))
+  return Promise.all([client, server]).then(() => undefined)
+}
+
+/**
+ * Bind one Zero mutator to local pending/error state without ever awaiting it.
+ *
+ *   const [insertPost, state] = useMutation(zero.mutate.post.insert)
+ *   insertPost({ ... })          // fires optimistically, returns immediately
+ *   state.error                  // render inline; client OR server failures land here
+ *   state.pending                // only to guard a re-submit, not to gate the UI
+ *
+ * The returned mutator has the exact same signature as the one passed in, so arg
+ * types are preserved. It returns Zero's native `{ client, server }` for the rare
+ * authoritative-wait escape hatch — product code should not await it. Every error
+ * also flows to `onMutationError` so a fire-and-forget call is never silent.
+ *
+ * For N writes use one custom mutator that loops `tx.mutate` in a single
+ * transaction, not N calls — that keeps it atomic and a single state.
+ */
+export function useMutation<Fn extends (...args: any[]) => MutatorResultLike>(
+  mutator: Fn,
+): [Fn, MutationState] {
+  const [pending, setPending] = useState(false)
+  const [error, setError] = useState<MutationError | null>(null)
+  const seqRef = useRef(0)
+  const mountedRef = useRef(true)
+  const mutatorRef = useRef(mutator)
+  mutatorRef.current = mutator
+
+  useEffect(() => {
+    mountedRef.current = true
+    return () => {
+      mountedRef.current = false
+    }
+  }, [])
+
+  const reset = useCallback(() => {
+    setError(null)
+    setPending(false)
+  }, [])
+
+  const run = useCallback((...args: any[]) => {
+    const result = mutatorRef.current(...args)
+    const seq = ++seqRef.current
+    setPending(true)
+    setError(null)
+
+    // latest-wins: only the most recent call's error/pending touch state
+    const isCurrent = () => mountedRef.current && seq === seqRef.current
+    observeMutation(result, (err) => {
+      if (isCurrent()) setError(err)
+    }).finally(() => {
+      if (isCurrent()) setPending(false)
+    })
+
+    return result
+  }, []) as Fn
+
+  return [run, { pending, error, reset }]
+}

package/src/index.ts

@@ -4,6 +4,7 @@ export * from './helpers/batchQuery'
 export * from './helpers/createMutators'
 export * from './helpers/ensureLoggedIn'
 export * from './helpers/mutatorContext'
+export * from './helpers/useMutation'
 export { ensureAuth, getAuth } from './helpers/getAuth'
 export { setAuthData, setEnvironment } from './state'
 

package/types/helpers/useMutation.d.ts

@@ -0,0 +1,47 @@
+type MutatorResultLike = {
+    client: Promise<unknown>;
+    server: Promise<unknown>;
+};
+export type MutationError = {
+    scope: 'client' | 'server';
+    kind: 'app' | 'zero';
+    message: string;
+    details?: unknown;
+};
+export type MutationState = {
+    pending: boolean;
+    error: MutationError | null;
+    reset: () => void;
+};
+export declare function onMutationError(cb: (error: MutationError) => void): () => void;
+/**
+ * Wire a mutation result's optimistic-client and authoritative-server phases to
+ * normalized errors, without awaiting either. Every error reaches the global
+ * `onMutationError` catch (deduped — client and server can surface the same
+ * failure); an optional `onError` sink receives them too (the hook uses it for
+ * local state). Use this directly for a fire-and-forget call outside React:
+ *
+ *   observeMutation(zero.mutate.post.delete({ id }))
+ *
+ * Resolves once both phases settle. Never rejects.
+ */
+export declare function observeMutation(result: MutatorResultLike, onError?: (error: MutationError) => void): Promise<void>;
+/**
+ * Bind one Zero mutator to local pending/error state without ever awaiting it.
+ *
+ *   const [insertPost, state] = useMutation(zero.mutate.post.insert)
+ *   insertPost({ ... })          // fires optimistically, returns immediately
+ *   state.error                  // render inline; client OR server failures land here
+ *   state.pending                // only to guard a re-submit, not to gate the UI
+ *
+ * The returned mutator has the exact same signature as the one passed in, so arg
+ * types are preserved. It returns Zero's native `{ client, server }` for the rare
+ * authoritative-wait escape hatch — product code should not await it. Every error
+ * also flows to `onMutationError` so a fire-and-forget call is never silent.
+ *
+ * For N writes use one custom mutator that loops `tx.mutate` in a single
+ * transaction, not N calls — that keeps it atomic and a single state.
+ */
+export declare function useMutation<Fn extends (...args: any[]) => MutatorResultLike>(mutator: Fn): [Fn, MutationState];
+export {};
+//# sourceMappingURL=useMutation.d.ts.map

package/types/helpers/useMutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMutation.d.ts","sourceRoot":"","sources":["../../src/helpers/useMutation.tsx"],"names":[],"mappings":"AAIA,KAAK,iBAAiB,GAAG;IACvB,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;IACxB,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CACzB,CAAA;AAOD,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC1B,IAAI,EAAE,KAAK,GAAG,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAI1B,OAAO,EAAE,OAAO,CAAA;IAEhB,KAAK,EAAE,aAAa,GAAG,IAAI,CAAA;IAC3B,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB,CAAA;AAOD,wBAAgB,eAAe,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI,CAK9E;AAsCD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GACvC,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,iBAAiB,EAC1E,OAAO,EAAE,EAAE,GACV,CAAC,EAAE,EAAE,aAAa,CAAC,CAsCrB"}

package/types/helpers/useMutation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=useMutation.test.d.ts.map

package/types/helpers/useMutation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMutation.test.d.ts","sourceRoot":"","sources":["../../src/helpers/useMutation.test.ts"],"names":[],"mappings":""}

package/types/index.d.ts

@@ -4,6 +4,7 @@ export * from './helpers/batchQuery';
 export * from './helpers/createMutators';
 export * from './helpers/ensureLoggedIn';
 export * from './helpers/mutatorContext';
+export * from './helpers/useMutation';
 export { ensureAuth, getAuth } from './helpers/getAuth';
 export { setAuthData, setEnvironment } from './state';
 export * from './createZeroClient';

package/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAErD,cAAc,oBAAoB,CAAA;AAClC,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,OAAO,CAAA;AACrB,OAAO,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAA;AACzD,cAAc,aAAa,CAAA;AAC3B,cAAc,SAAS,CAAA;AACvB,cAAc,eAAe,CAAA;AAC7B,cAAc,OAAO,CAAA;AACrB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAM3D,mBAAmB,SAAS,CAAA;AAE5B,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,GAChC,MAAM,+BAA+B,CAAA;AACtC,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,GACzB,MAAM,+BAA+B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,uBAAuB,CAAA;AACrC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAErD,cAAc,oBAAoB,CAAA;AAClC,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,OAAO,CAAA;AACrB,OAAO,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAA;AACzD,cAAc,aAAa,CAAA;AAC3B,cAAc,SAAS,CAAA;AACvB,cAAc,eAAe,CAAA;AAC7B,cAAc,OAAO,CAAA;AACrB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAM3D,mBAAmB,SAAS,CAAA;AAE5B,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,GAChC,MAAM,+BAA+B,CAAA;AACtC,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,GACzB,MAAM,+BAA+B,CAAA"}