@abloatai/humans 0.37.0

package/src/react/useMutationFailureListener.ts

@@ -0,0 +1,34 @@
+'use client';
+
+import { useContext, useEffect, useRef } from 'react';
+import {
+  AbloInternalContext,
+  type QueuedMutation,
+} from '../reactRuntime.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+
+export interface MutationFailurePayload {
+  transaction: QueuedMutation;
+  error: Error;
+  permanent?: boolean;
+}
+
+/** Subscribe to optimistic mutation rollbacks and permanent write failures. */
+export function useMutationFailureListener(
+  listener: (payload: MutationFailurePayload) => void,
+): void {
+  const context = useContext(AbloInternalContext);
+  if (!context) {
+    throw new AbloValidationError(
+      'useMutationFailureListener: no <AbloProvider> mounted above this component.',
+      { code: 'no_ablo_provider' },
+    );
+  }
+  const listenerRef = useRef(listener);
+  listenerRef.current = listener;
+  useEffect(() => {
+    const engine = context.engine;
+    if (!engine) return;
+    return engine.onMutationFailure((payload) => listenerRef.current(payload));
+  }, [context, context.engine]);
+}

package/src/react/useMutators.ts

@@ -0,0 +1,184 @@
+'use client';
+
+import { useMemo } from 'react';
+import type { Schema } from '@abloatai/transaction/schema/schema';
+import type {
+  MutatorDefs,
+  MutatorFn,
+} from '../local/mutators/defineMutators.js';
+import { createTransaction } from '../local/mutators/Transaction.js';
+import { createRecordingMutation } from '../local/mutators/RecordingMutation.js';
+import type { UndoScope } from '../local/mutators/UndoManager.js';
+import type { ResolveSchema } from '@abloatai/transaction/types/global';
+import { useSyncContext } from './context.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+import { getContext } from '../local/context.js';
+
+/**
+ * Turns a mutator tree built with `defineMutators` into callable invokers. The
+ * returned object mirrors that tree one-to-one, but each leaf becomes an
+ * `(args) => Promise<TResult>` function.
+ *
+ * Each invocation builds a fresh `Transaction` bound to the current store and
+ * organization, calls your mutator with `{ tx, args }`, and returns whatever
+ * the mutator resolves to.
+ *
+ * If a mutator throws, the error propagates to the caller and any writes it
+ * already dispatched stay in place — there is no automatic rollback. Wrap the
+ * call in your own try/catch and issue compensating writes when you need to
+ * undo a partial change, or pass an `undoScope` (see {@link UseMutatorsOptions})
+ * to record inverses for undo and redo.
+ */
+
+/**
+ * Map a `MutatorFn` onto its invoker form — strip `tx`, keep `args`/return.
+ *
+ * Uses nested `infer O` so the `args`/`result` types are extracted from the
+ * function signature without binding the `tx` parameter to a specific
+ * `Transaction<S>` variance. Function parameters are contravariant, so a
+ * match against `MutatorFn<Schema>` would reject mutators declared against
+ * a narrower schema (e.g. `Transaction<typeof appSchema>`). The two-step
+ * inference sidesteps that without resorting to `any`/`unknown` placeholders.
+ */
+export type InvokerFor<F> = F extends (options: infer O) => Promise<infer R>
+  ? O extends { args: infer A }
+    ? (args: A) => Promise<R>
+    : never
+  : never;
+
+/**
+ * The hook's return shape: same tree as the input `MutatorDefs`, every leaf
+ * rewritten to its invoker form.
+ */
+export type MutatorInvokers<M> = {
+  [K in keyof M]: {
+    [N in keyof M[K]]: InvokerFor<M[K][N]>;
+  };
+};
+
+/**
+ * Options passed to `useMutators`. When `undoScope` is set, every mutator
+ * invocation is wrapped in a `RecordingMutation` and its inverses are
+ * pushed to the scope as one undo entry.
+ */
+export interface UseMutatorsOptions<S extends Schema> {
+  /** Target undo scope for recording inverses. Omit to disable recording. */
+  undoScope?: UndoScope<S>;
+}
+
+/** Mutator invokers (explicit schema arg). */
+export function useMutators<S extends Schema, M extends MutatorDefs<S>>(
+  schema: S,
+  mutators: M,
+  options?: UseMutatorsOptions<S>,
+): MutatorInvokers<M>;
+
+/** Mutator invokers via the `Register` module augmentation. Schema comes
+ * from the `SyncProvider`'s context; the mutator tree is typed against
+ * `ResolveSchema` at the call site. */
+export function useMutators<
+  M extends ResolveSchema extends Schema ? MutatorDefs<ResolveSchema> : MutatorDefs<Schema>,
+>(
+  mutators: M,
+  options?: UseMutatorsOptions<ResolveSchema extends Schema ? ResolveSchema : Schema>,
+): MutatorInvokers<M>;
+
+export function useMutators(
+  schemaOrMutators: Schema | MutatorDefs<Schema>,
+  mutatorsOrOptions?: MutatorDefs<Schema> | UseMutatorsOptions<Schema>,
+  maybeOptions?: UseMutatorsOptions<Schema>,
+): MutatorInvokers<MutatorDefs<Schema>> {
+  const { store, organizationId, schema: ctxSchema } = useSyncContext();
+
+  // Disambiguate: explicit-schema path has the schema object in first slot;
+  // the global-resolved path has the mutator tree there. A schema object
+  // has a `.models` property; a mutator tree doesn't.
+  const isExplicit =
+    typeof schemaOrMutators === 'object' &&
+    schemaOrMutators !== null &&
+    'models' in schemaOrMutators;
+
+  const schema = isExplicit ? (schemaOrMutators as Schema) : ctxSchema;
+  const mutators = (isExplicit ? mutatorsOrOptions : schemaOrMutators) as MutatorDefs<Schema>;
+  const options = (isExplicit ? maybeOptions : mutatorsOrOptions) as
+    | UseMutatorsOptions<Schema>
+    | undefined;
+
+  if (!schema) {
+    throw new AbloValidationError(
+      'useMutators: no schema available. Pass the schema as the first arg, ' +
+        'or build the <AbloProvider> above with `Ablo({ schema })` so the ' +
+        'zero-arg overload can read it from context.',
+      { code: 'mutators_schema_missing' },
+    );
+  }
+
+  const { undoScope } = options ?? {};
+
+  return useMemo<MutatorInvokers<MutatorDefs<Schema>>>(() => {
+    const out: Record<string, Record<string, (args: unknown) => Promise<unknown>>> = {};
+
+    for (const modelKey of Object.keys(mutators)) {
+      const group = (mutators as Record<string, Record<string, MutatorFn<Schema, unknown, unknown>>>)[modelKey];
+      if (!group) continue;
+
+      const invokers: Record<string, (args: unknown) => Promise<unknown>> = {};
+      for (const mutatorName of Object.keys(group)) {
+        const maybeFn = group[mutatorName];
+        if (!maybeFn) continue;
+        // Bind the narrowed value: `noUncheckedIndexedAccess` types the indexed
+        // read as `Fn | undefined`, and that narrowing doesn't survive into the
+        // deferred invoker closures below — a non-optional local does.
+        const fn = maybeFn;
+        const label = `${String(modelKey)}.${mutatorName}`;
+
+        invokers[mutatorName] = async (args: unknown) => {
+          // Recording path: wrap the transaction so each write snapshots its
+          // inverse. On success, push the captured entry to the scope.
+          //
+          // The whole snapshot → write → record sequence runs on the scope's
+          // serialization chain so concurrent invocations (a caller may fire
+          // writes without awaiting them) record in invocation order and never
+          // interleave their shared-model snapshots. See UndoScope.runRecorded.
+          if (undoScope) {
+            return undoScope.runRecorded(async () => {
+              const recording = createRecordingMutation(schema, store, organizationId);
+              try {
+                const result = await fn({ tx: recording.tx, args });
+                const entry = recording.getEntry(label);
+                if (entry) undoScope.record(entry);
+                return result;
+              } catch (err) {
+                // The error is re-thrown to the caller's await (the real
+                // consumer surface), so this is a forensic follow-on → debug.
+                getContext().logger.debug(
+                  `[useMutators] mutator "${label}" threw`,
+                  { error: err },
+                );
+                throw err;
+              }
+            });
+          }
+
+          // Non-recording path — plain transaction, no inverse capture.
+          const tx = createTransaction(schema, store, organizationId);
+          try {
+            return await fn({ tx, args });
+          } catch (err) {
+            // Re-thrown to the caller's await (the real consumer surface) →
+            // this duplicate is forensic, debug only.
+            getContext().logger.debug(
+              `[useMutators] mutator "${label}" threw`,
+              { error: err },
+            );
+            throw err;
+          }
+        };
+      }
+
+      out[modelKey] = invokers;
+    }
+
+    return out;
+  }, [schema, mutators, store, organizationId, undoScope]);
+}

package/src/react/useSyncStatus.ts

@@ -0,0 +1,42 @@
+'use client';
+
+import { useCallback } from 'react';
+import {
+  useSyncContext,
+  type SyncStoreContract,
+} from './context.js';
+import { useReactive } from '../useReactive.js';
+
+export type SyncStatusSnapshot =
+  | { readonly name: 'initial' }
+  | { readonly name: 'connecting'; readonly progress: number }
+  | { readonly name: 'connected'; readonly hasUnsyncedChanges: boolean }
+  | { readonly name: 'reconnecting'; readonly reason?: string }
+  | { readonly name: 'disconnected'; readonly reason?: string }
+  | { readonly name: 'needs-auth' };
+
+/** Reactively exposes the local store's connection and settlement status. */
+export function useSyncStatus(): SyncStatusSnapshot {
+  const { store } = useSyncContext();
+  const compute = useCallback(() => deriveStatus(store), [store]);
+  return useReactive(compute, sameSnapshot);
+}
+
+function deriveStatus(store: SyncStoreContract): SyncStatusSnapshot {
+  const { state, progress, pendingChanges, isSessionError, error } = store.syncStatus;
+  if (isSessionError) return { name: 'needs-auth' };
+  if (state === 'reconnecting') return { name: 'reconnecting', reason: error?.message };
+  if (state === 'offline') return { name: 'disconnected', reason: 'offline' };
+  if (state === 'error') return { name: 'disconnected', reason: error?.message };
+  if (store.isReady) return { name: 'connected', hasUnsyncedChanges: pendingChanges > 0 };
+  if (state === 'idle' || state === 'syncing') return { name: 'connecting', progress };
+  return { name: 'initial' };
+}
+
+function sameSnapshot(a: SyncStatusSnapshot, b: SyncStatusSnapshot): boolean {
+  if (a.name !== b.name) return false;
+  if (a.name === 'initial' || a.name === 'needs-auth') return true;
+  if (a.name === 'connecting') return b.name === 'connecting' && a.progress === b.progress;
+  if (a.name === 'connected') return b.name === 'connected' && a.hasUnsyncedChanges === b.hasUnsyncedChanges;
+  return (b.name === 'reconnecting' || b.name === 'disconnected') && a.reason === b.reason;
+}

package/src/react/useUndoScope.ts

@@ -0,0 +1,143 @@
+'use client';
+
+import { useEffect, useMemo, useState } from 'react';
+import type { Schema } from '@abloatai/transaction/schema/schema';
+import {
+  UndoManager,
+  type UndoScope,
+  type UndoScopeOptions,
+} from '../local/mutators/UndoManager.js';
+import type { ResolveSchema } from '@abloatai/transaction/types/global';
+import { useSyncContext } from './context.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+
+/**
+ * Provides per-surface undo and redo for mutator invocations. Each named scope
+ * owns an independent undo/redo stack, so different parts of your app — a main
+ * editor, a sidebar form — can undo separately without stepping on each other.
+ *
+ * Wire the returned `scope` into `useMutators(schema, mutators, { undoScope:
+ * scope })` and those invocations become recorded. `undo()` and `redo()` replay
+ * the captured inverses and forwards as new transactions that do not record
+ * themselves; the manager moves the entry between the two stacks explicitly.
+ *
+ * @example
+ * const { undo, redo, canUndo, canRedo, scope } = useUndoScope('report-editor');
+ * const mutate = useMutators(schema, reportMutators, { undoScope: scope });
+ *
+ * // Cmd+Z handler
+ * useHotkey('mod+z', () => { if (canUndo) void undo(); });
+ */
+
+export interface UseUndoScopeResult<S extends Schema> {
+  /** Pass to `useMutators(..., { undoScope })` to enable recording. */
+  scope: UndoScope<S>;
+  undo: () => Promise<void>;
+  redo: () => Promise<void>;
+  canUndo: boolean;
+  canRedo: boolean;
+  /** Drop history. Use after sync errors / auth context changes. */
+  clear: () => void;
+}
+
+// Module-level weak registry: `SyncStoreContract` → `UndoManager`.
+// A single app wiring through one SyncProvider shares one manager across
+// every useUndoScope call, so scopes with the same name are identity-equal.
+// The hook implementation already operates on the runtime-wide `Schema` type;
+// its overloads restore the caller's precise schema type at the public boundary,
+// so the registry can keep that same non-generic runtime representation.
+const managers = new WeakMap<object, UndoManager<Schema>>();
+
+function getManager(
+  key: object,
+  factory: () => UndoManager<Schema>,
+): UndoManager<Schema> {
+  let m = managers.get(key);
+  if (!m) {
+    const created = factory();
+    managers.set(key, created);
+    m = created;
+  }
+  return m;
+}
+
+/** Per-surface undo/redo (explicit schema arg). */
+export function useUndoScope<S extends Schema>(
+  schema: S,
+  name: string,
+  options?: UndoScopeOptions,
+): UseUndoScopeResult<S>;
+
+/** Per-surface undo/redo via the `Register` module augmentation. */
+export function useUndoScope(
+  name: string,
+  options?: UndoScopeOptions,
+): UseUndoScopeResult<ResolveSchema extends Schema ? ResolveSchema : Schema>;
+
+export function useUndoScope(
+  schemaOrName: Schema | string,
+  nameOrOptions?: string | UndoScopeOptions,
+  maybeOptions?: UndoScopeOptions,
+): UseUndoScopeResult<Schema> {
+  const { store, organizationId, schema: ctxSchema } = useSyncContext();
+
+  const isExplicit = typeof schemaOrName !== 'string';
+  const schema = isExplicit ? (schemaOrName) : ctxSchema;
+  const name = isExplicit ? (nameOrOptions as string) : schemaOrName;
+  const options = (isExplicit ? maybeOptions : nameOrOptions) as UndoScopeOptions | undefined;
+
+  if (!schema) {
+    throw new AbloValidationError(
+      'useUndoScope: no schema available. Pass the schema as the first arg, ' +
+        'or build the <AbloProvider> above with `Ablo({ schema })` so the ' +
+        'zero-arg overload can read it from context.',
+      { code: 'undo_scope_schema_missing' },
+    );
+  }
+
+  const scope = useMemo(() => {
+    // Store is the identity for the manager — one per SyncProvider.
+    const manager = getManager(store, () => new UndoManager(schema, store, organizationId));
+    return manager.getScope(name, options);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [store, organizationId, name]);
+
+  // Local tick forces re-render after undo/redo/clear so canUndo/canRedo
+  // reflect the new stack sizes. The scope itself doesn't emit React-
+  // friendly notifications; callers that want cross-component reactivity
+  // can wire a mobx observable or custom event bus on top.
+  const [, setTick] = useState(0);
+
+  // Reset tick when scope identity changes (new store / new orgId).
+  useEffect(() => {
+    setTick(0);
+  }, [scope]);
+
+  // Re-render on any stack change — including entries recorded from the local-
+  // mutation stream, which don't otherwise trigger a React update. Without this
+  // `canUndo`/`canRedo` go stale in every consumer that didn't itself call
+  // undo/redo (e.g. a keyboard handler whose Cmd+Z gate then never fires).
+  useEffect(() => {
+    return scope.onChange(() => { setTick((t: number) => t + 1); });
+  }, [scope]);
+
+  const size = scope.size();
+
+  return {
+    scope,
+    undo: async () => {
+      await scope.undo();
+      setTick((t: number) => t + 1);
+    },
+    redo: async () => {
+      await scope.redo();
+      setTick((t: number) => t + 1);
+    },
+    canUndo: size.undo > 0,
+    canRedo: size.redo > 0,
+    clear: () => {
+      scope.clear();
+      setTick((t: number) => t + 1);
+    },
+  };
+}

package/src/react.ts

@@ -0,0 +1,69 @@
+/** React bindings for the optional human-facing local-state package. */
+export { useReactive } from './useReactive.js';
+export { useCurrentUserId } from './react/useCurrentUserId.js';
+export { useErrorListener } from './react/useErrorListener.js';
+export { useSyncStatus, type SyncStatusSnapshot } from './react/useSyncStatus.js';
+export {
+  useMutationFailureListener,
+  type MutationFailurePayload,
+} from './react/useMutationFailureListener.js';
+
+export {
+  AbloProvider,
+  useJoin,
+  usePeers,
+  useSync,
+  useSyncStore,
+  type AbloProviderProps,
+  type ParticipantScope,
+  type ParticipantStatus,
+  type UseJoinOptions,
+  type UseJoinReturn,
+} from './react/AbloProvider.js';
+
+export {
+  ClientSideSuspense,
+  type ClientSideSuspenseProps,
+} from './react/ClientSideSuspense.js';
+
+export { DefaultFallback } from './react/DefaultFallback.js';
+
+export {
+  createAbloReact,
+  type AbloReactBinding,
+} from './react/createAbloReact.js';
+
+export {
+  useAblo,
+  type UseAbloHydratedModelResult,
+  type UseAbloModelOptions,
+  type UseAbloModelResult,
+} from './react/useAblo.js';
+
+export {
+  useMutators,
+  type InvokerFor,
+  type MutatorInvokers,
+  type UseMutatorsOptions,
+} from './react/useMutators.js';
+
+export {
+  useUndoScope,
+  type UseUndoScopeResult,
+} from './react/useUndoScope.js';
+
+export type {
+  DefaultSyncShape,
+  ResolveSchema,
+  ResolveUserMeta,
+  ResolveClaimMeta,
+  ResolveModelKey,
+} from '@abloatai/transaction/types/global';
+
+export { ModelScope } from '@abloatai/transaction/types';
+export type { SyncStoreContract } from './react/context.js';
+export type { MutateActions } from './local/mutators/mutateActions.js';
+export type {
+  ReaderActions,
+  ReaderFindOptions,
+} from './local/mutators/readerActions.js';

package/src/reactRuntime.ts

@@ -0,0 +1,10 @@
+export {
+  AbloInternalContext,
+  type AbloInternalContextValue,
+} from './react/internalContext.js';
+export {
+  useSyncContext,
+  type SyncReactContext,
+} from './react/context.js';
+export type { SyncStoreContract } from './local/storeContract.js';
+export type { QueuedMutation } from './local/transactions/mutations/MutationQueue.js';

package/src/surface.ts

@@ -0,0 +1,106 @@
+/**
+ * A machine-checked manifest of this package's public API surface. It lists,
+ * as string tuples, the method names on `ablo.<model>`, the keys accepted by
+ * the list-style read options, and the keys of the client constructor
+ * options. Each tuple is proven equal to the keys of its source interface at
+ * compile time, so the lists cannot drift from the real types: add or remove
+ * a name on either side without updating the matching tuple and this file
+ * fails to compile, in both directions — no name the interface lacks, and no
+ * interface key the tuple omits.
+ *
+ * Documentation tooling reads these tuples to describe the surface, which
+ * guarantees a generated summary never names a method or option that does
+ * not exist. The names are verified here; their prose descriptions are
+ * written by hand, since prose cannot be type-checked.
+ */
+
+import type { ModelOperations, LocalReadOptions } from './local/client/createModelProxy.js';
+import type { AbloOptions } from './Ablo.js';
+
+// ── compile-time exact-equality (no runtime, no casts) ─────────────────────
+// Standard invariant type-equality: true only when A and B are mutually assignable.
+type Equal<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+// `Expect<T extends true>` errors at the declaration when T is `false`.
+type Expect<T extends true> = T;
+
+// ── the per-`ablo.<model>` verb surface ────────────────────────────────────
+/**
+ * The names of every method available on `ablo.<model>`, matching the keys of
+ * the {@link ModelOperations} interface. Documentation tooling reads this
+ * tuple, so it is the one list of model-verb names a generated summary can
+ * describe.
+ */
+export const PUBLIC_MODEL_VERBS = [
+  'get',
+  'retrieve',
+  'list',
+  'local',
+  'create',
+  'update',
+  'delete',
+  'claim',
+  'track',
+  'join',
+  'onChange',
+] as const;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type _ModelVerbsExact = Expect<
+  Equal<(typeof PUBLIC_MODEL_VERBS)[number], keyof ModelOperations<unknown, unknown> & string>
+>;
+
+// ── the read/list query option surface ─────────────────────────────────────
+/**
+ * The option keys accepted by `local.list` and `onChange`, matching the
+ * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named
+ * `state`, not `scope`.
+ */
+export const PUBLIC_LIST_OPTION_KEYS = [
+  'where',
+  'filter',
+  'orderBy',
+  'limit',
+  'offset',
+  'state',
+] as const;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type _ListOptionKeysExact = Expect<
+  Equal<(typeof PUBLIC_LIST_OPTION_KEYS)[number], keyof LocalReadOptions<unknown> & string>
+>;
+
+// ── the `Ablo({ … })` constructor option surface ───────────────────────────
+/**
+ * The keys of the client constructor options, {@link AbloOptions}. Only
+ * `schema` is required; every other key is optional.
+ */
+export const PUBLIC_ABLO_OPTION_KEYS = [
+  'schema',
+  'apiKey',
+  'authEndpoint',
+  'authTimeoutMs',
+  'allowCrossOriginAuthEndpoint',
+  'persistence',
+  'durableWrites',
+  'commitOutbox',
+  'commitOutboxScope',
+  'debug',
+  'logLevel',
+  'logger',
+  'authToken',
+  'baseURL',
+  'fetch',
+  'defaultHeaders',
+  'defaultQuery',
+  'dangerouslyAllowBrowser',
+  'collaborationEvents',
+  'plugins',
+  'wait',
+] as const;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type _AbloOptionKeysExact = Expect<
+  Equal<(typeof PUBLIC_ABLO_OPTION_KEYS)[number], keyof AbloOptions & string>
+>;
+
+export type ModelVerb = (typeof PUBLIC_MODEL_VERBS)[number];
+export type ListOptionKey = (typeof PUBLIC_LIST_OPTION_KEYS)[number];
+export type AbloOptionKey = (typeof PUBLIC_ABLO_OPTION_KEYS)[number];

package/src/useReactive.ts

@@ -0,0 +1,51 @@
+'use client';
+
+import { useCallback, useRef } from 'react';
+import { useSyncExternalStore } from 'react';
+import { reaction } from 'mobx';
+
+/**
+ * Subscribe a React component to a MobX computation with a cached snapshot.
+ * This is the framework-level reactive primitive owned by @abloatai/humans;
+ * store/model hooks are layered above it.
+ */
+export function useReactive<T>(
+  compute: () => T,
+  equals: (a: T, b: T) => boolean = defaultEquals,
+): T {
+  const computeRef = useRef(compute);
+  const equalsRef = useRef(equals);
+  const snapshotRef = useRef<{ value: T } | null>(null);
+  const versionRef = useRef(0);
+
+  equalsRef.current = equals;
+  if (snapshotRef.current === null) {
+    snapshotRef.current = { value: compute() };
+  } else if (computeRef.current !== compute) {
+    const next = compute();
+    if (!equals(snapshotRef.current.value, next)) {
+      snapshotRef.current = { value: next };
+      versionRef.current++;
+    }
+  }
+  computeRef.current = compute;
+
+  const subscribe = useCallback((onChange: () => void) => reaction(
+    () => computeRef.current(),
+    (next) => {
+      const current = snapshotRef.current!.value;
+      if (!equalsRef.current(current, next)) {
+        snapshotRef.current = { value: next };
+        onChange();
+      }
+    },
+  ), [versionRef.current]);
+  const getSnapshot = useCallback(() => snapshotRef.current!.value, []);
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+function defaultEquals<T>(a: T, b: T): boolean {
+  if (Object.is(a, b)) return true;
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+  return a.every((value, index) => Object.is(value, b[index]));
+}