hazo_config 2.4.3 → 2.5.0

package/CHANGE_LOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 2.5.0 — 2026-09-06
+
+### Added
+
+Ecosystem-first promotion of taxclientdocs' two-tier (global default +
+scope-level override) config helpers, previously duplicated in
+`lib/config/{two-tier,clone-to-override,override-count}.ts`.
+
+- `mergeTwoTier<T>(opts): T[]` (`src/lib/two_tier.ts`, exported from the main
+  entry and `hazo_config/lib`) — pure, zero-dep merge of a `globals[]` +
+  `overrides[]` row pair (each shaped `{ id, scope_id, enabled, ... }`) into
+  the effective list. Override wins by key (via `keyFn`); an `additive` mode
+  returns the union of both tiers instead. `TwoTierRow`/`MergeOptions` types
+  exported alongside. No database dependency — callers fetch `globals`/
+  `overrides` however they like, matching the existing `AppConfig`
+  callback-persistence pattern.
+- New `hazo_config/server-data` entry point: `cloneToOverride(table,
+  globalRowId, orgScopeId)` / `CloneToOverrideError` and
+  `getOverrideCount(table, keyColumn, keyValue)` (`src/lib/clone_to_override.ts`,
+  `src/lib/override_count.ts`) — hazo_connect-backed CRUD helpers for cloning
+  a global row into a scope-level override and counting existing overrides
+  for a key. Kept in a separate entry point (not `/server` or `/lib`) so a
+  consumer of the fs-based `HazoConfig` or the pure `mergeTwoTier` is never
+  required to install `hazo_connect`. `hazo_connect` added as an **optional**
+  peer dependency (`^4.1.0`) accordingly.
+
 ## 2.4.2 — 2026-08-04
 
 ### Changed

package/dist/lib/clone_to_override.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Purpose: Clone a global (platform-default) two-tier config row into a
+ * scope-level override row.
+ *
+ * hazo_connect is an optional peer dependency here (see `hazo_config/server-data`,
+ * the entry point that re-exports this). It is loaded via dynamic import()
+ * with bundler-ignore hints, matching `config_loader.ts`'s optional
+ * `hazo_core/errors` integration: `hazo_connect/server` and
+ * `hazo_connect/nextjs/setup` are ESM-only subpath exports, and this
+ * package's build uses moduleResolution:"node" (predates subpath-exports
+ * resolution), so TS can't resolve them statically even though they load
+ * fine at runtime.
+ */
+export declare class CloneToOverrideError extends Error {
+    constructor(message: string);
+}
+/**
+ * Clone the global row `globalRowId` from `table` into a new row scoped to
+ * `orgScopeId`. Strips `id`/`created_at`/`updated_at` and stamps
+ * `cloned_from_at` on the new row.
+ *
+ * @throws {CloneToOverrideError} when the source row does not exist, is not
+ * itself a global row (`scope_id` must be `null`), or the insert returns no row.
+ */
+export declare function cloneToOverride(table: string, globalRowId: string, orgScopeId: string): Promise<Record<string, unknown>>;
+//# sourceMappingURL=clone_to_override.d.ts.map

package/dist/lib/clone_to_override.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone_to_override.d.ts","sourceRoot":"","sources":["../../src/lib/clone_to_override.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA0BH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAoBlC"}

package/dist/lib/clone_to_override.js

@@ -0,0 +1,60 @@
+/**
+ * Purpose: Clone a global (platform-default) two-tier config row into a
+ * scope-level override row.
+ *
+ * hazo_connect is an optional peer dependency here (see `hazo_config/server-data`,
+ * the entry point that re-exports this). It is loaded via dynamic import()
+ * with bundler-ignore hints, matching `config_loader.ts`'s optional
+ * `hazo_core/errors` integration: `hazo_connect/server` and
+ * `hazo_connect/nextjs/setup` are ESM-only subpath exports, and this
+ * package's build uses moduleResolution:"node" (predates subpath-exports
+ * resolution), so TS can't resolve them statically even though they load
+ * fine at runtime.
+ */
+async function loadCreateCrudService() {
+    // @ts-ignore — hazo_connect/server is a valid subpath export; moduleResolution:"node"
+    // predates subpath exports so TS can't resolve it statically, but it loads correctly at runtime.
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    const mod = (await import(/* turbopackIgnore: true */ /* webpackIgnore: true */ 'hazo_connect/server'));
+    return mod.createCrudService;
+}
+async function loadGetHazoConnectSingleton() {
+    // @ts-ignore — hazo_connect/nextjs/setup is a valid subpath export; see loadCreateCrudService above.
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    const mod = (await import(/* turbopackIgnore: true */ /* webpackIgnore: true */ 'hazo_connect/nextjs/setup'));
+    return mod.getHazoConnectSingleton;
+}
+export class CloneToOverrideError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CloneToOverrideError';
+    }
+}
+/**
+ * Clone the global row `globalRowId` from `table` into a new row scoped to
+ * `orgScopeId`. Strips `id`/`created_at`/`updated_at` and stamps
+ * `cloned_from_at` on the new row.
+ *
+ * @throws {CloneToOverrideError} when the source row does not exist, is not
+ * itself a global row (`scope_id` must be `null`), or the insert returns no row.
+ */
+export async function cloneToOverride(table, globalRowId, orgScopeId) {
+    const createCrudService = await loadCreateCrudService();
+    const getHazoConnectSingleton = await loadGetHazoConnectSingleton();
+    const svc = createCrudService(getHazoConnectSingleton(), table);
+    const row = await svc.findById(globalRowId);
+    if (!row)
+        throw new CloneToOverrideError('Global row not found');
+    if (row.scope_id !== null)
+        throw new CloneToOverrideError('Source row is not a global (scope_id must be null)');
+    // Strip the id and timestamps; set new scope
+    const { id: _omit, created_at: _ca, updated_at: _ua, ...rest } = row;
+    const inserted = await svc.insert({
+        ...rest,
+        scope_id: orgScopeId,
+        cloned_from_at: new Date().toISOString(),
+    });
+    if (!inserted[0])
+        throw new CloneToOverrideError('Insert returned no row');
+    return inserted[0];
+}

package/dist/lib/index.d.ts

@@ -12,4 +12,6 @@ export { MockConfigProvider } from './mock_config_provider.js';
 export { ConfigErrorCode } from './types.js';
 export type { ConfigProvider, HazoConfigOptions, Logger, HazoConfigError, LogData } from './types.js';
 export type { ConfigType, AppConfigItem, AppConfigContext, AppConfigProps, UseAppConfigResult } from './app_config_types.js';
+export { mergeTwoTier } from './two_tier.js';
+export type { TwoTierRow, MergeOptions } from './two_tier.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAC5C,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,MAAM,EACN,eAAe,EACf,OAAO,EACR,MAAM,YAAY,CAAA;AAGnB,YAAY,EACV,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EACnB,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAC5C,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,MAAM,EACN,eAAe,EACf,OAAO,EACR,MAAM,YAAY,CAAA;AAGnB,YAAY,EACV,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EACnB,MAAM,uBAAuB,CAAA;AAK9B,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA"}

package/dist/lib/index.js

@@ -11,3 +11,7 @@
 // Client-safe exports (no Node.js dependencies)
 export { MockConfigProvider } from './mock_config_provider.js';
 export { ConfigErrorCode } from './types.js';
+// Two-tier (global default + scope-level override) merge -- pure, no
+// database dependency. See 'hazo_config/server-data' for the hazo_connect-
+// backed clone/override-count helpers that operate on the same shape.
+export { mergeTwoTier } from './two_tier.js';

package/dist/lib/override_count.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Purpose: Count scope-level override rows for a two-tier config key.
+ *
+ * hazo_connect is an optional peer dependency here (see `hazo_config/server-data`,
+ * the entry point that re-exports this) and is loaded via dynamic import()
+ * for the same reason as `clone_to_override.ts` -- see that file's header.
+ */
+/**
+ * Count how many override (non-global) rows exist in `table` for the given
+ * `keyColumn`/`keyValue`. A row counts as an override when its `scope_id`
+ * is not `null`.
+ */
+export declare function getOverrideCount(table: string, keyColumn: string, keyValue: string): Promise<number>;
+//# sourceMappingURL=override_count.d.ts.map

package/dist/lib/override_count.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"override_count.d.ts","sourceRoot":"","sources":["../../src/lib/override_count.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA8BH;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAOjB"}

package/dist/lib/override_count.js

@@ -0,0 +1,32 @@
+/**
+ * Purpose: Count scope-level override rows for a two-tier config key.
+ *
+ * hazo_connect is an optional peer dependency here (see `hazo_config/server-data`,
+ * the entry point that re-exports this) and is loaded via dynamic import()
+ * for the same reason as `clone_to_override.ts` -- see that file's header.
+ */
+async function loadCreateCrudService() {
+    // @ts-ignore — hazo_connect/server is a valid subpath export; moduleResolution:"node"
+    // predates subpath exports so TS can't resolve it statically, but it loads correctly at runtime.
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    const mod = (await import(/* turbopackIgnore: true */ /* webpackIgnore: true */ 'hazo_connect/server'));
+    return mod.createCrudService;
+}
+async function loadGetHazoConnectSingleton() {
+    // @ts-ignore — hazo_connect/nextjs/setup is a valid subpath export; see loadCreateCrudService above.
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    const mod = (await import(/* turbopackIgnore: true */ /* webpackIgnore: true */ 'hazo_connect/nextjs/setup'));
+    return mod.getHazoConnectSingleton;
+}
+/**
+ * Count how many override (non-global) rows exist in `table` for the given
+ * `keyColumn`/`keyValue`. A row counts as an override when its `scope_id`
+ * is not `null`.
+ */
+export async function getOverrideCount(table, keyColumn, keyValue) {
+    const createCrudService = await loadCreateCrudService();
+    const getHazoConnectSingleton = await loadGetHazoConnectSingleton();
+    const svc = createCrudService(getHazoConnectSingleton(), table);
+    const rows = (await svc.list((q) => q.where(keyColumn, 'eq', keyValue).select('id,scope_id'))) ?? [];
+    return rows.filter((r) => r.scope_id !== null).length;
+}

package/dist/lib/two_tier.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Purpose: Two-tier (global default + scope-level override) config merge.
+ *
+ * Companion to the AppConfig database-backed configuration story (see
+ * `app_config_types.ts`): a global row has `scope_id: null`; an override row
+ * has the caller's `scope_id` and shadows the global row that shares its key.
+ * Pure and framework-agnostic -- the caller fetches `globals`/`overrides`
+ * however it likes (hazo_connect, a plain fetch, a mock) and passes both
+ * arrays in.
+ */
+/**
+ * Minimum shape a two-tier row must have. `scope_id: null` marks a global
+ * (platform-default) row; any other value marks a scope-level override.
+ */
+export interface TwoTierRow {
+    id: string;
+    scope_id: string | null;
+    enabled: boolean;
+    [k: string]: unknown;
+}
+/**
+ * Options for {@link mergeTwoTier}.
+ */
+export interface MergeOptions<T extends TwoTierRow> {
+    /** Platform-default rows (`scope_id: null`). */
+    globals: T[];
+    /** Scope-level override rows. */
+    overrides: T[];
+    /** Extracts the key two rows are matched on (e.g. a `code` column, or a composite of several columns). */
+    keyFn: (row: T) => string;
+    /**
+     * When true, skip key-based shadowing entirely and return the union of
+     * enabled globals and enabled overrides (both tiers additive, not
+     * override-wins-by-key).
+     */
+    additive?: boolean;
+}
+/**
+ * Merge a global/override row pair into the effective list.
+ *
+ * Default (non-additive) mode: for each key, an override row shadows the
+ * global row that shares it; a key present only in one tier passes through
+ * as-is. A row (global or override) is included only while `enabled` is
+ * true -- an override with `enabled: false` hides an enabled global at the
+ * same key, and a disabled global stays hidden unless an override
+ * re-enables it.
+ *
+ * Additive mode (`additive: true`) skips key matching and returns every
+ * enabled row from both tiers.
+ *
+ * @example
+ * mergeTwoTier({
+ *   globals: [{ id: 'g1', scope_id: null, code: 'invoice', enabled: true }],
+ *   overrides: [{ id: 'o1', scope_id: 'org-A', code: 'invoice', enabled: true }],
+ *   keyFn: (r) => r.code,
+ * })
+ * // -> [{ id: 'o1', scope_id: 'org-A', code: 'invoice', enabled: true }]
+ */
+export declare function mergeTwoTier<T extends TwoTierRow>(opts: MergeOptions<T>): T[];
+//# sourceMappingURL=two_tier.d.ts.map

package/dist/lib/two_tier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"two_tier.d.ts","sourceRoot":"","sources":["../../src/lib/two_tier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,OAAO,EAAE,OAAO,CAAA;IAChB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,UAAU;IAChD,gDAAgD;IAChD,OAAO,EAAE,CAAC,EAAE,CAAA;IACZ,iCAAiC;IACjC,SAAS,EAAE,CAAC,EAAE,CAAA;IACd,0GAA0G;IAC1G,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,CAAA;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAyB7E"}

package/dist/lib/two_tier.js

@@ -0,0 +1,56 @@
+/**
+ * Purpose: Two-tier (global default + scope-level override) config merge.
+ *
+ * Companion to the AppConfig database-backed configuration story (see
+ * `app_config_types.ts`): a global row has `scope_id: null`; an override row
+ * has the caller's `scope_id` and shadows the global row that shares its key.
+ * Pure and framework-agnostic -- the caller fetches `globals`/`overrides`
+ * however it likes (hazo_connect, a plain fetch, a mock) and passes both
+ * arrays in.
+ */
+/**
+ * Merge a global/override row pair into the effective list.
+ *
+ * Default (non-additive) mode: for each key, an override row shadows the
+ * global row that shares it; a key present only in one tier passes through
+ * as-is. A row (global or override) is included only while `enabled` is
+ * true -- an override with `enabled: false` hides an enabled global at the
+ * same key, and a disabled global stays hidden unless an override
+ * re-enables it.
+ *
+ * Additive mode (`additive: true`) skips key matching and returns every
+ * enabled row from both tiers.
+ *
+ * @example
+ * mergeTwoTier({
+ *   globals: [{ id: 'g1', scope_id: null, code: 'invoice', enabled: true }],
+ *   overrides: [{ id: 'o1', scope_id: 'org-A', code: 'invoice', enabled: true }],
+ *   keyFn: (r) => r.code,
+ * })
+ * // -> [{ id: 'o1', scope_id: 'org-A', code: 'invoice', enabled: true }]
+ */
+export function mergeTwoTier(opts) {
+    const { globals, overrides, keyFn, additive } = opts;
+    if (additive) {
+        return [...globals, ...overrides].filter((r) => r.enabled);
+    }
+    const overrideByKey = new Map();
+    for (const r of overrides)
+        overrideByKey.set(keyFn(r), r);
+    const result = [];
+    const seenKeys = new Set();
+    for (const g of globals) {
+        const k = keyFn(g);
+        seenKeys.add(k);
+        const override = overrideByKey.get(k);
+        const effective = override ?? g;
+        if (effective.enabled)
+            result.push(effective);
+    }
+    for (const o of overrides) {
+        const k = keyFn(o);
+        if (!seenKeys.has(k) && o.enabled)
+            result.push(o);
+    }
+    return result;
+}

package/dist/server-data/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * hazo_connect-backed data helpers for hazo_config
+ *
+ * This entry point contains code that depends on `hazo_connect` (an
+ * optional peer dependency), separate from `hazo_config/server` (which is
+ * Node fs/path-only for the INI-backed `HazoConfig`) and the main/`/lib`
+ * entry points (pure, no database dependency). Only import from here if you
+ * have `hazo_connect` installed and want the two-tier global/override CRUD
+ * helpers -- consumers of `HazoConfig` or `mergeTwoTier` alone are
+ * unaffected either way.
+ *
+ * Usage:
+ *   import { cloneToOverride, getOverrideCount } from 'hazo_config/server-data'
+ */
+export { cloneToOverride, CloneToOverrideError } from '../lib/clone_to_override.js';
+export { getOverrideCount } from '../lib/override_count.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/server-data/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server-data/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AACnF,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/server-data/index.js

@@ -0,0 +1,16 @@
+/**
+ * hazo_connect-backed data helpers for hazo_config
+ *
+ * This entry point contains code that depends on `hazo_connect` (an
+ * optional peer dependency), separate from `hazo_config/server` (which is
+ * Node fs/path-only for the INI-backed `HazoConfig`) and the main/`/lib`
+ * entry points (pure, no database dependency). Only import from here if you
+ * have `hazo_connect` installed and want the two-tier global/override CRUD
+ * helpers -- consumers of `HazoConfig` or `mergeTwoTier` alone are
+ * unaffected either way.
+ *
+ * Usage:
+ *   import { cloneToOverride, getOverrideCount } from 'hazo_config/server-data'
+ */
+export { cloneToOverride, CloneToOverrideError } from '../lib/clone_to_override.js';
+export { getOverrideCount } from '../lib/override_count.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_config",
-  "version": "2.4.3",
+  "version": "2.5.0",
   "description": "Config wrapper with error handling",
   "type": "module",
   "main": "dist/index.js",
@@ -30,6 +30,11 @@
       "types": "./dist/lib/index.d.ts",
       "import": "./dist/lib/index.js",
       "default": "./dist/lib/index.js"
+    },
+    "./server-data": {
+      "types": "./dist/server-data/index.d.ts",
+      "import": "./dist/server-data/index.js",
+      "default": "./dist/server-data/index.js"
     }
   },
   "scripts": {
@@ -91,7 +96,7 @@
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
     "@vitejs/plugin-react": "^4.2.0",
-    "hazo_connect": "^4.0.0",
+    "hazo_connect": "^4.1.0",
     "jsdom": "^24.1.3",
     "postcss": "^8.4.49",
     "react": "^18.2.0",
@@ -103,14 +108,18 @@
     "vitest": "^4.0.15"
   },
   "peerDependencies": {
-    "hazo_core": "^2.0.0",
-    "hazo_theme": "^1.3.0",
-    "hazo_ui": "^6.8.0",
+    "hazo_connect": "^4.1.0",
+    "hazo_core": "^2.2.0",
+    "hazo_theme": "^1.3.1",
+    "hazo_ui": "^6.11.2",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "tailwindcss": "^4.0.0"
   },
   "peerDependenciesMeta": {
+    "hazo_connect": {
+      "optional": true
+    },
     "hazo_core": {
       "optional": true
     },