hazo_state 0.1.2 → 0.2.0

package/CHANGE_LOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to this package are documented here. Versions follow semver.
 
+## 0.2.0 — 2026-07-21
+
+### Added
+- **`resolveHydratedValue<T>(local, remote, opts?)`** — new pure export from
+  `hazo_state/client`. Reconciles a "local-first" candidate against a "remote"
+  candidate for the common localStorage-then-DB hydration pattern: absent side
+  falls back to whichever is present; when both are present, an injectable
+  `opts.merge(local, remote)` decides the outcome, defaulting to **remote-wins**
+  when no `merge` is supplied. No React, no DOM, no fetch — safe to unit-test
+  without jsdom and reusable outside a hook (scripts, server-side reconciliation,
+  etc). 10 unit tests (this package's first-ever test suite, run via the
+  already-declared `vitest` dev dependency — no new test infra needed).
+
+### Not shipped (scope note)
+- A full `useSyncedLocalState<T>` hook (localStorage-first hydrate + debounced
+  remote save + silent-degrade-on-failure) was evaluated as the natural next
+  layer on top of `resolveHydratedValue`, extracted from stocktools'
+  `tax-situation-context.tsx`. **Deliberately deferred** — see
+  `design/DECISIONS.md` D-004 for the concrete race condition found during
+  design that blocked a confident port. FR-021 filed as `planned`, not
+  `shipped`.
+
 ## 0.1.2 — 2026-06-12
 
 ### Fixed

package/dist/client/index.d.ts

@@ -1,4 +1,6 @@
 import type { StateLevel } from '../index.js';
+export { resolveHydratedValue } from './resolve_hydrated_value.js';
+export type { ResolveHydratedValueOptions } from './resolve_hydrated_value.js';
 export interface UseHazoStateOptions {
     /** Visibility level. Default: 'global'. */
     level?: StateLevel;

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,aAAa,CAAA;AAKzD,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,sDAAsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAA;IACd,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnF,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC1C,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACpB;AA0BD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,GAAG,kBAAkB,CA+K5F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,aAAa,CAAA;AAGzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAClE,YAAY,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAA;AAI9E,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,sDAAsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAA;IACd,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnF,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC1C,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACpB;AA0BD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,GAAG,kBAAkB,CA+K5F"}

package/dist/client/index.js

@@ -13,6 +13,7 @@
  */
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { ConflictError } from '../index.js';
+export { resolveHydratedValue } from './resolve_hydrated_value.js';
 const DEFAULT_ENDPOINT = '/api/hazo-state';
 function storageKey(key, level, prefix) {
     return prefix ? `${prefix}:${key}` : `hazo_state:${level}:${key}`;

package/dist/client/resolve_hydrated_value.d.ts

@@ -0,0 +1,35 @@
+/**
+ * hazo_state/client — resolveHydratedValue
+ *
+ * Pure reconciliation step for "localStorage-first, then merge with a remote
+ * copy" hydration. Deliberately has NO React, NO DOM, NO fetch — just the
+ * decision of what value wins once a local candidate and a remote candidate
+ * are both known (or absent). This is the seam a stateful hook (or any other
+ * transport) plugs into; keeping it pure makes it unit-testable without a
+ * DOM/jsdom environment and reusable outside a hook (e.g. a one-shot script).
+ *
+ * Default policy: **remote wins when present**. `null`/`undefined` on either
+ * side falls back to whichever side is available. Callers needing a different
+ * reconciliation (field-level merge, local-wins, newest-timestamp-wins, …)
+ * inject an explicit `merge` function — the default is a policy choice, not a
+ * hardcoded rule.
+ */
+export interface ResolveHydratedValueOptions<T> {
+    /**
+     * Called only when BOTH `local` and `remote` are present (non-null,
+     * non-undefined). Its return value wins outright. Omit to use the default
+     * "remote wins" policy.
+     */
+    merge?: (local: T, remote: T) => T;
+}
+/**
+ * Reconciles a local candidate and a remote candidate into the value a
+ * consumer should hydrate with.
+ *
+ * - Both absent → `null`.
+ * - Only one present → that one.
+ * - Both present, no `merge` supplied → `remote` (default policy).
+ * - Both present, `merge` supplied → `merge(local, remote)`.
+ */
+export declare function resolveHydratedValue<T>(local: T | null | undefined, remote: T | null | undefined, opts?: ResolveHydratedValueOptions<T>): T | null;
+//# sourceMappingURL=resolve_hydrated_value.d.ts.map

package/dist/client/resolve_hydrated_value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve_hydrated_value.d.ts","sourceRoot":"","sources":["../../src/client/resolve_hydrated_value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,2BAA2B,CAAC,CAAC;IAC5C;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAC3B,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAC5B,IAAI,CAAC,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACpC,CAAC,GAAG,IAAI,CASV"}

package/dist/client/resolve_hydrated_value.js

@@ -0,0 +1,36 @@
+/**
+ * hazo_state/client — resolveHydratedValue
+ *
+ * Pure reconciliation step for "localStorage-first, then merge with a remote
+ * copy" hydration. Deliberately has NO React, NO DOM, NO fetch — just the
+ * decision of what value wins once a local candidate and a remote candidate
+ * are both known (or absent). This is the seam a stateful hook (or any other
+ * transport) plugs into; keeping it pure makes it unit-testable without a
+ * DOM/jsdom environment and reusable outside a hook (e.g. a one-shot script).
+ *
+ * Default policy: **remote wins when present**. `null`/`undefined` on either
+ * side falls back to whichever side is available. Callers needing a different
+ * reconciliation (field-level merge, local-wins, newest-timestamp-wins, …)
+ * inject an explicit `merge` function — the default is a policy choice, not a
+ * hardcoded rule.
+ */
+/**
+ * Reconciles a local candidate and a remote candidate into the value a
+ * consumer should hydrate with.
+ *
+ * - Both absent → `null`.
+ * - Only one present → that one.
+ * - Both present, no `merge` supplied → `remote` (default policy).
+ * - Both present, `merge` supplied → `merge(local, remote)`.
+ */
+export function resolveHydratedValue(local, remote, opts) {
+    const hasLocal = local !== null && local !== undefined;
+    const hasRemote = remote !== null && remote !== undefined;
+    if (!hasLocal && !hasRemote)
+        return null;
+    if (!hasRemote)
+        return local;
+    if (!hasLocal)
+        return remote;
+    return opts?.merge ? opts.merge(local, remote) : remote;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_state",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Generic transactional KV store for the hazo ecosystem — TTL, optimistic CAS, atomic helpers, turnkey route/client",
   "type": "module",
   "main": "dist/index.js",
@@ -55,7 +55,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "hazo_connect": "^3.5.1",
+    "hazo_connect": "^3.7.0",
     "server-only": "^0.0.1"
   },
   "devDependencies": {