on-zero 0.4.49 → 0.4.50

package/src/createUseQueryDirect.tsx

@@ -15,6 +15,7 @@ import {
   type UseQueryOptions,
 } from './createUseQuery'
 import { resolveQuery } from './resolveQuery'
+import { useContentStable } from './useContentStable'
 
 import type {
   AnyQueryRegistry,
@@ -327,12 +328,20 @@ export function createUseQueryDirect<Schema extends ZeroSchema>({
     }, [queryRequest, enabled, ttl, version])
 
     const getEmpty = () => emptyForQuery as DirectSnapshot
-    const out = useSyncExternalStore(
+    const rawOut = useSyncExternalStore(
       view ? view.subscribe : DISABLED_SUBSCRIBE,
       view ? view.getSnapshot : getEmpty,
       view ? view.getSnapshot : getEmpty,
     )
 
+    // content-stable inner refs (see createUseQuery.tsx for the rationale).
+    const stableData = useContentStable(rawOut[0])
+    const stableInfo = useContentStable(rawOut[1])
+    const out: DirectSnapshot =
+      stableData !== rawOut[0] || stableInfo !== rawOut[1]
+        ? ([stableData, stableInfo] as DirectSnapshot)
+        : rawOut
+
     if (!disableMode) {
       lastRef.current = out
       return out

package/src/useContentStable.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest'
+import { isContentEqual } from './useContentStable'
+
+describe('isContentEqual', () => {
+  it('treats primitives by value', () => {
+    expect(isContentEqual(1, 1)).toBe(true)
+    expect(isContentEqual('a', 'a')).toBe(true)
+    expect(isContentEqual(true, true)).toBe(true)
+    expect(isContentEqual(undefined, undefined)).toBe(true)
+    expect(isContentEqual(null, null)).toBe(true)
+    expect(isContentEqual(1, 2)).toBe(false)
+    expect(isContentEqual('a', 'b')).toBe(false)
+    expect(isContentEqual(null, undefined)).toBe(false)
+  })
+
+  it('treats arrays by length + per-element strict-eq', () => {
+    expect(isContentEqual([], [])).toBe(true)
+    expect(isContentEqual([1, 2, 3], [1, 2, 3])).toBe(true)
+    expect(isContentEqual([1, 2, 3], [1, 2])).toBe(false)
+    expect(isContentEqual([1, 2, 3], [1, 2, 4])).toBe(false)
+    // distinct objects with same fields → strict-eq fails per element
+    expect(isContentEqual([{ id: 1 }], [{ id: 1 }])).toBe(false)
+    // same object ref shared → strict-eq holds
+    const row = { id: 1 }
+    expect(isContentEqual([row], [row])).toBe(true)
+  })
+
+  it('treats objects by same keys + per-value strict-eq', () => {
+    expect(isContentEqual({}, {})).toBe(true)
+    expect(isContentEqual({ a: 1, b: 2 }, { a: 1, b: 2 })).toBe(true)
+    expect(isContentEqual({ a: 1 }, { a: 1, b: 2 })).toBe(false)
+    expect(isContentEqual({ a: 1 }, { a: 2 })).toBe(false)
+    // distinct nested objects → strict-eq fails on the nested value
+    expect(isContentEqual({ row: { id: 1 } }, { row: { id: 1 } })).toBe(false)
+  })
+
+  it('rejects mismatched array vs object', () => {
+    expect(isContentEqual([], {})).toBe(false)
+    expect(isContentEqual([1], { 0: 1 })).toBe(false)
+  })
+
+  it('handles a typical zero singular-query refresh — same row content', () => {
+    // simulating zero's deepClone: the row is a fresh object but every field
+    // matches the previous snapshot. shallow strict-eq sees fresh nested but
+    // top-level keys are primitives → equal.
+    const prev = { id: 's1', name: 'warden', level: 1, hp: 60, maxHp: 60 }
+    const next = { id: 's1', name: 'warden', level: 1, hp: 60, maxHp: 60 }
+    expect(isContentEqual(prev, next)).toBe(true)
+  })
+
+  it('detects a real refresh — one field changed', () => {
+    const prev = { id: 's1', hp: 60 }
+    const next = { id: 's1', hp: 59 }
+    expect(isContentEqual(prev, next)).toBe(false)
+  })
+
+  it('handles zero info objects ({type: "complete"} vs {type: "unknown"})', () => {
+    expect(isContentEqual({ type: 'complete' }, { type: 'complete' })).toBe(true)
+    expect(isContentEqual({ type: 'complete' }, { type: 'unknown' })).toBe(false)
+  })
+})

package/src/useContentStable.ts

@@ -0,0 +1,78 @@
+// content-stable identity for useQuery's inner data + info values.
+//
+// upstream zero-react's view does `data = deepClone(snap)` inside #onData
+// whenever the materialized view notifies, which means each notification
+// produces a fresh JS reference even when the row's content hasn't changed.
+// consumers that destructure `[row] = useQuery(byId, {id})` and then use
+// `row` as a useEffect dep — or that depend on `[rows]` for a list query —
+// see a "change" on every notification and re-run effects redundantly.
+//
+// `useContentStable(value)` keeps a ref to the previous value and returns the
+// old reference when shallow-content equality holds, so downstream identity
+// comparisons (`useMemo`, `useEffect`, `useCallback`) don't false-fire.
+//
+// equality semantics:
+//   - primitives + same-reference                  → return as-is
+//   - arrays: same length + each element strict-eq → reuse previous ref
+//   - objects: same keys + each value strict-eq    → reuse previous ref
+//   - mismatches                                   → swap the ref forward
+//
+// the per-element check is strict-eq (not recursive). that's intentional —
+// it catches the common case where a query result is the same row(s) on a
+// re-emit. for nested-object stability the rows themselves get the same
+// treatment one level up (the wrapping useQuery already applies this to
+// `data` so an array-of-rows query holds row references stable if each row
+// content-matches its previous snapshot row).
+
+import { useRef } from 'react'
+
+function arraysShallowEqual(a: readonly unknown[], b: readonly unknown[]): boolean {
+  if (a === b) return true
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (!Object.is(a[i], b[i])) return false
+  }
+  return true
+}
+
+function objectsShallowEqual(a: object, b: object): boolean {
+  if (a === b) return true
+  const ak = Object.keys(a as Record<string, unknown>)
+  const bk = Object.keys(b as Record<string, unknown>)
+  if (ak.length !== bk.length) return false
+  for (const k of ak) {
+    if (
+      !Object.is(
+        (a as Record<string, unknown>)[k],
+        (b as Record<string, unknown>)[k],
+      )
+    )
+      return false
+  }
+  return true
+}
+
+export function isContentEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (a === null || b === null || a === undefined || b === undefined) return false
+  if (typeof a !== 'object' || typeof b !== 'object') return false
+  const aIsArr = Array.isArray(a)
+  const bIsArr = Array.isArray(b)
+  if (aIsArr !== bIsArr) return false
+  if (aIsArr && bIsArr) {
+    return arraysShallowEqual(a as readonly unknown[], b as readonly unknown[])
+  }
+  return objectsShallowEqual(a as object, b as object)
+}
+
+// returns `value` on first render, then returns the previous reference for as
+// long as content-equality holds. mutating the ref during render is safe here
+// because we read its current value AFTER deciding whether to swap — no read-
+// then-write race that React would warn about.
+export function useContentStable<T>(value: T): T {
+  const ref = useRef<T>(value)
+  if (!isContentEqual(ref.current, value)) {
+    ref.current = value
+  }
+  return ref.current
+}

package/types/createUseQuery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createUseQuery.d.ts","sourceRoot":"","sources":["../src/createUseQuery.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAE/D,OAAO,EAA+B,KAAK,OAAO,EAAE,MAAM,OAAO,CAAA;AAGjE,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAEhE,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,KAAK,EACL,MAAM,IAAI,UAAU,EACpB,GAAG,EACJ,MAAM,gBAAgB,CAAA;AAGvB,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,OAAO,GAAG,YAAY,CAAA;AAE7D,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,GAAG,CAAC,EAAE,GAAG,GAAG,SAAS,CAAA;CACtB,CAAA;AAED,KAAK,kBAAkB,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;AAC5D,MAAM,MAAM,WAAW,CAAC,OAAO,IAAI,SAAS,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC,CAAA;AAExF,YAAY,EAAE,YAAY,EAAE,CAAA;AAE5B,MAAM,MAAM,YAAY,CAAC,MAAM,SAAS,UAAU,IAAI;IAEpD,CAAC,IAAI,EAAE,MAAM,SAAS,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,OAAO,EAC5D,EAAE,EAAE,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,EACtD,MAAM,EAAE,IAAI,EACZ,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,GAClC,WAAW,CAAC,OAAO,CAAC,CAAC;IAGxB,CAAC,MAAM,SAAS,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,OAAO,EACtD,EAAE,EAAE,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,EACtD,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,GAClC,WAAW,CAAC,OAAO,CAAC,CAAA;CACxB,CAAA;AAiBD,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,OAAO,GAAG,SAAS,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAU5F;AAGD,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG;;;EAYtE;AAED,wBAAgB,cAAc,CAAC,MAAM,SAAS,UAAU,EAAE,EACxD,eAAe,EACf,aAAa,GACd,EAAE;IACD,eAAe,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC1C,aAAa,EAAE,gBAAgB,CAAA;CAChC,GAAG,YAAY,CAAC,MAAM,CAAC,CAwGvB"}
+{"version":3,"file":"createUseQuery.d.ts","sourceRoot":"","sources":["../src/createUseQuery.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAE/D,OAAO,EAA+B,KAAK,OAAO,EAAE,MAAM,OAAO,CAAA;AAGjE,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAGhE,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,KAAK,EACL,MAAM,IAAI,UAAU,EACpB,GAAG,EACJ,MAAM,gBAAgB,CAAA;AAGvB,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,OAAO,GAAG,YAAY,CAAA;AAE7D,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,GAAG,CAAC,EAAE,GAAG,GAAG,SAAS,CAAA;CACtB,CAAA;AAED,KAAK,kBAAkB,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;AAC5D,MAAM,MAAM,WAAW,CAAC,OAAO,IAAI,SAAS,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC,CAAA;AAExF,YAAY,EAAE,YAAY,EAAE,CAAA;AAE5B,MAAM,MAAM,YAAY,CAAC,MAAM,SAAS,UAAU,IAAI;IAEpD,CAAC,IAAI,EAAE,MAAM,SAAS,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,OAAO,EAC5D,EAAE,EAAE,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,EACtD,MAAM,EAAE,IAAI,EACZ,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,GAClC,WAAW,CAAC,OAAO,CAAC,CAAC;IAGxB,CAAC,MAAM,SAAS,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,OAAO,EACtD,EAAE,EAAE,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,EACtD,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,GAClC,WAAW,CAAC,OAAO,CAAC,CAAA;CACxB,CAAA;AAiBD,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,OAAO,GAAG,SAAS,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAU5F;AAGD,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG;;;EAYtE;AAED,wBAAgB,cAAc,CAAC,MAAM,SAAS,UAAU,EAAE,EACxD,eAAe,EACf,aAAa,GACd,EAAE;IACD,eAAe,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC1C,aAAa,EAAE,gBAAgB,CAAA;CAChC,GAAG,YAAY,CAAC,MAAM,CAAC,CAoHvB"}

package/types/createUseQueryDirect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createUseQueryDirect.d.ts","sourceRoot":"","sources":["../src/createUseQueryDirect.tsx"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAA;AACjE,OAAO,EAAqD,KAAK,OAAO,EAAE,MAAM,OAAO,CAAA;AAEvF,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAElB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,KAAK,EACV,gBAAgB,EAEhB,MAAM,IAAI,UAAU,EACrB,MAAM,gBAAgB,CAAA;AAkBvB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,CACT,KAAK,EAAE,GAAG,EACV,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,GAAG,CAAA;KAAE,GACtB;QACD,WAAW,CACT,EAAE,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB,KAAK,IAAI,GACpE,IAAI,CAAA;QACP,OAAO,IAAI,IAAI,CAAA;QACf,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAA;KAC1B,CAAA;CACF,CAAA;AAED,MAAM,MAAM,oBAAoB,CAAC,MAAM,SAAS,UAAU,IAAI,CAAC,KAAK,EAAE;IACpE,eAAe,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC1C,aAAa,EAAE,gBAAgB,CAAA;IAC/B,OAAO,EAAE,MAAM,kBAAkB,GAAG,IAAI,CAAA;IACxC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;CAC7B,KAAK,YAAY,CAAC,MAAM,CAAC,CAAA;AAG1B,KAAK,gBAAgB,GAAG;IACtB,KAAK,EAAE,KAAK,GAAG,OAAO,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AA2LD,wBAAgB,oBAAoB,CAAC,MAAM,SAAS,UAAU,EAAE,EAC9D,eAAe,EACf,aAAa,EACb,OAAO,EACP,WAAW,GACZ,EAAE,UAAU,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,CAyFpE"}
+{"version":3,"file":"createUseQueryDirect.d.ts","sourceRoot":"","sources":["../src/createUseQueryDirect.tsx"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAA;AACjE,OAAO,EAAqD,KAAK,OAAO,EAAE,MAAM,OAAO,CAAA;AAEvF,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAElB,MAAM,kBAAkB,CAAA;AAIzB,OAAO,KAAK,EACV,gBAAgB,EAEhB,MAAM,IAAI,UAAU,EACrB,MAAM,gBAAgB,CAAA;AAkBvB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,CACT,KAAK,EAAE,GAAG,EACV,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,GAAG,CAAA;KAAE,GACtB;QACD,WAAW,CACT,EAAE,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB,KAAK,IAAI,GACpE,IAAI,CAAA;QACP,OAAO,IAAI,IAAI,CAAA;QACf,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAA;KAC1B,CAAA;CACF,CAAA;AAED,MAAM,MAAM,oBAAoB,CAAC,MAAM,SAAS,UAAU,IAAI,CAAC,KAAK,EAAE;IACpE,eAAe,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC1C,aAAa,EAAE,gBAAgB,CAAA;IAC/B,OAAO,EAAE,MAAM,kBAAkB,GAAG,IAAI,CAAA;IACxC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;CAC7B,KAAK,YAAY,CAAC,MAAM,CAAC,CAAA;AAG1B,KAAK,gBAAgB,GAAG;IACtB,KAAK,EAAE,KAAK,GAAG,OAAO,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AA2LD,wBAAgB,oBAAoB,CAAC,MAAM,SAAS,UAAU,EAAE,EAC9D,eAAe,EACf,aAAa,EACb,OAAO,EACP,WAAW,GACZ,EAAE,UAAU,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,CAiGpE"}

package/types/useContentStable.d.ts

@@ -0,0 +1,3 @@
+export declare function isContentEqual(a: unknown, b: unknown): boolean;
+export declare function useContentStable<T>(value: T): T;
+//# sourceMappingURL=useContentStable.d.ts.map

package/types/useContentStable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useContentStable.d.ts","sourceRoot":"","sources":["../src/useContentStable.ts"],"names":[],"mappings":"AAsDA,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAW9D;AAMD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAM/C"}

package/types/useContentStable.test.d.ts

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

package/types/useContentStable.test.d.ts.map

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