hazo_core 1.0.0

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAG3F,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGvE,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,KAAK,EACL,WAAW,EACX,eAAe,EACf,cAAc,EACd,eAAe,EACf,cAAc,EACd,YAAY,EACZ,aAAa,EACb,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,GACd,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,gBAAgB,EAChB,0BAA0B,EAC1B,eAAe,EACf,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EACzB,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,WAAW,EACX,UAAU,EACV,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAG3E,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD,OAAO,EACL,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,27 @@
+/**
+ * hazo_core — server entry point (Node.js)
+ *
+ * Exports all public API surface. See architecture.md §5 for the public API spec.
+ * Browser-safe consumers should use 'hazo_core/client' instead.
+ */
+// Constants
+export { REQUEST_ID_HEADER, HAZO_ERROR_SYMBOL, HAZO_SINGLETONS_KEY } from './constants.js';
+// Singleton registry
+export { registerSingleton, getSingleton } from './singleton/index.js';
+// Utilities
+export { getCurrentEnv, generateRequestId, optional_import, safeJsonParse, sleep, formatBytes, formatDateShort, formatDateLong, formatDateSlash, formatCurrency, formatNumber, formatBoolean, getInitials, format_date, format_date_range, DEFAULT_DATE_FORMAT, } from './utils/index.js';
+// Errors
+export { HazoError, HazoValidationError, HazoAuthError, HazoNotFoundError, HazoConflictError, HazoConfigError, HazoExternalError, HazoRateLimitError, HazoUnavailableError, HazoInternalError, fromZodValidation, fromZodConfig, } from './errors/index.js';
+// Context (server — AsyncLocalStorage)
+export { withContext, getContext, getCorrelationId, } from './context/index.js';
+// Config
+export { loadConfig, defineConfig, reloadConfig } from './config/index.js';
+// Logger
+export { createLogger } from './logger/index.js';
+// Debug
+export { createDebug } from './debug/index.js';
+// HTTP
+export { createRequestIdMiddleware, withRequestIdRouteHandler, } from './http/request_id_middleware.js';
+export { fetchWithRequestId } from './http/fetch_with_request_id.js';
+export { get_origin_url, create_redirect_url } from './http/get_origin_url.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY;AACZ,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE3F,qBAAqB;AACrB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEvE,YAAY;AACZ,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,KAAK,EACL,WAAW,EACX,eAAe,EACf,cAAc,EACd,eAAe,EACf,cAAc,EACd,YAAY,EACZ,aAAa,EACb,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAG1B,SAAS;AACT,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,GACd,MAAM,mBAAmB,CAAC;AAe3B,uCAAuC;AACvC,OAAO,EACL,WAAW,EACX,UAAU,EACV,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAG5B,SAAS;AACT,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE3E,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,QAAQ;AACR,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,OAAO;AACP,OAAO,EACL,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/logger/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * hazo_core logger factory — wraps hazo_logs and auto-injects:
+ *   - pkg (the passed name)
+ *   - correlationId (from getCorrelationId() at call time)
+ *   - env (from getCurrentEnv() at module load time)
+ *
+ * Falls back to a minimal stderr JSON writer when hazo_logs is not installed.
+ *
+ * Per architecture.md §9 and D-002.
+ */
+export interface HazoCoreLogger {
+    trace(event: string, fields?: Record<string, unknown>): void;
+    debug(event: string, fields?: Record<string, unknown>): void;
+    info(event: string, fields?: Record<string, unknown>): void;
+    warn(event: string, fields?: Record<string, unknown>): void;
+    error(event: string, fields?: Record<string, unknown>): void;
+    /** Create a child logger that merges fixed fields into every call. */
+    child(fields: Record<string, unknown>): HazoCoreLogger;
+}
+/**
+ * Create a logger for a hazo package.
+ *
+ * When hazo_logs is installed, wraps its createLogger and auto-injects
+ * correlationId, env, and pkg into every log entry.
+ *
+ * When hazo_logs is absent, writes JSON lines to process.stderr.
+ */
+export declare function createLogger(pkg: string): HazoCoreLogger;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,sEAAsE;IACtE,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAAC;CACxD;AAqID;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAUxD"}

package/dist/logger/index.js

@@ -0,0 +1,125 @@
+/**
+ * hazo_core logger factory — wraps hazo_logs and auto-injects:
+ *   - pkg (the passed name)
+ *   - correlationId (from getCorrelationId() at call time)
+ *   - env (from getCurrentEnv() at module load time)
+ *
+ * Falls back to a minimal stderr JSON writer when hazo_logs is not installed.
+ *
+ * Per architecture.md §9 and D-002.
+ */
+import { createRequire } from 'node:module';
+import { getCurrentEnv } from '../utils/env.js';
+// ---------------------------------------------------------------------------
+// Detect hazo_logs at module init time (synchronous, CJS require via createRequire)
+// ---------------------------------------------------------------------------
+const _require = createRequire(import.meta.url);
+let hazoLogsModule = null;
+try {
+    hazoLogsModule = _require('hazo_logs');
+}
+catch {
+    // hazo_logs not installed — fallback to stderr writer below
+}
+// ---------------------------------------------------------------------------
+// Resolve correlationId lazily (avoid circular import with context/server.ts)
+// ---------------------------------------------------------------------------
+function getCorrelationIdLazy() {
+    try {
+        // The ALS is registered on globalThis by context/server.ts at import time.
+        // We read it from there to avoid a direct circular dependency.
+        const store = globalThis['__hazo_core_context_store__'];
+        if (store && typeof store === 'object' && 'getStore' in store) {
+            const ctx = store.getStore();
+            return ctx?.['correlationId'];
+        }
+    }
+    catch {
+        // Context not available — ignore
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Fallback logger (hazo_logs absent)
+// ---------------------------------------------------------------------------
+const LEVEL_ORDER = {
+    trace: 0,
+    debug: 1,
+    info: 2,
+    warn: 3,
+    error: 4,
+};
+function writeStderr(level, pkg, event, fields, fixedFields) {
+    const entry = {
+        level,
+        pkg,
+        event,
+        ...fixedFields,
+        ...fields,
+        correlationId: getCorrelationIdLazy(),
+        env: getCurrentEnv(),
+        ts: new Date().toISOString(),
+    };
+    process.stderr.write(JSON.stringify(entry) + '\n');
+}
+function makeFallbackLogger(pkg, fixedFields = {}) {
+    const log = (level) => (event, fields = {}) => {
+        // Only emit levels >= info by default to avoid noise
+        if ((LEVEL_ORDER[level] ?? 0) >= (LEVEL_ORDER['info'] ?? 2)) {
+            writeStderr(level, pkg, event, fields, fixedFields);
+        }
+    };
+    return {
+        trace: log('trace'),
+        debug: log('debug'),
+        info: log('info'),
+        warn: log('warn'),
+        error: log('error'),
+        child: (childFields) => makeFallbackLogger(pkg, { ...fixedFields, ...childFields }),
+    };
+}
+// ---------------------------------------------------------------------------
+// hazo_logs wrapper
+// ---------------------------------------------------------------------------
+function makeWrappedLogger(inner, pkg, fixedFields = {}) {
+    const inject = (fields = {}) => ({
+        pkg,
+        ...fixedFields,
+        ...fields,
+        correlationId: getCorrelationIdLazy(),
+        env: getCurrentEnv(),
+    });
+    return {
+        // hazo_logs Logger interface has no 'trace' level — map to debug
+        trace: (event, fields = {}) => inner.debug(event, inject(fields)),
+        debug: (event, fields = {}) => inner.debug(event, inject(fields)),
+        info: (event, fields = {}) => inner.info(event, inject(fields)),
+        warn: (event, fields = {}) => inner.warn(event, inject(fields)),
+        error: (event, fields = {}) => inner.error(event, inject(fields)),
+        child: (childFields) => makeWrappedLogger(inner, pkg, { ...fixedFields, ...childFields }),
+    };
+}
+// ---------------------------------------------------------------------------
+// Public factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a logger for a hazo package.
+ *
+ * When hazo_logs is installed, wraps its createLogger and auto-injects
+ * correlationId, env, and pkg into every log entry.
+ *
+ * When hazo_logs is absent, writes JSON lines to process.stderr.
+ */
+export function createLogger(pkg) {
+    if (hazoLogsModule) {
+        try {
+            const inner = hazoLogsModule.createLogger(pkg);
+            return makeWrappedLogger(inner, pkg);
+        }
+        catch {
+            // Fall through to fallback
+        }
+    }
+    return makeFallbackLogger(pkg);
+}
+//# sourceMappingURL=index.js.map

package/dist/logger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAgBhD,8EAA8E;AAC9E,oFAAoF;AACpF,8EAA8E;AAE9E,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAYhD,IAAI,cAAc,GAA0B,IAAI,CAAC;AACjD,IAAI,CAAC;IACH,cAAc,GAAG,QAAQ,CAAC,WAAW,CAAmB,CAAC;AAC3D,CAAC;AAAC,MAAM,CAAC;IACP,4DAA4D;AAC9D,CAAC;AAED,8EAA8E;AAC9E,8EAA8E;AAC9E,8EAA8E;AAE9E,SAAS,oBAAoB;IAC3B,IAAI,CAAC;QACH,2EAA2E;QAC3E,+DAA+D;QAC/D,MAAM,KAAK,GAAI,UAAsC,CAAC,6BAA6B,CAAC,CAAC;QACrF,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,IAAI,KAAK,EAAE,CAAC;YAC9D,MAAM,GAAG,GAAI,KAA6D,CAAC,QAAQ,EAAE,CAAC;YACtF,OAAO,GAAG,EAAE,CAAC,eAAe,CAAuB,CAAC;QACtD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,iCAAiC;IACnC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,8EAA8E;AAC9E,qCAAqC;AACrC,8EAA8E;AAE9E,MAAM,WAAW,GAA2B;IAC1C,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACT,CAAC;AAEF,SAAS,WAAW,CAClB,KAAa,EACb,GAAW,EACX,KAAa,EACb,MAA+B,EAC/B,WAAoC;IAEpC,MAAM,KAAK,GAAG;QACZ,KAAK;QACL,GAAG;QACH,KAAK;QACL,GAAG,WAAW;QACd,GAAG,MAAM;QACT,aAAa,EAAE,oBAAoB,EAAE;QACrC,GAAG,EAAE,aAAa,EAAE;QACpB,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KAC7B,CAAC;IACF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,kBAAkB,CACzB,GAAW,EACX,cAAuC,EAAE;IAEzC,MAAM,GAAG,GACP,CAAC,KAAa,EAAE,EAAE,CAClB,CAAC,KAAa,EAAE,SAAkC,EAAE,EAAQ,EAAE;QAC5D,qDAAqD;QACrD,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YAC5D,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QACtD,CAAC;IACH,CAAC,CAAC;IAEJ,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC;QACnB,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC;QACnB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC;QACjB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC;QACjB,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC;QACnB,KAAK,EAAE,CAAC,WAAW,EAAE,EAAE,CACrB,kBAAkB,CAAC,GAAG,EAAE,EAAE,GAAG,WAAW,EAAE,GAAG,WAAW,EAAE,CAAC;KAC9D,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,SAAS,iBAAiB,CACxB,KAAiD,EACjD,GAAW,EACX,cAAuC,EAAE;IAEzC,MAAM,MAAM,GAAG,CAAC,SAAkC,EAAE,EAA2B,EAAE,CAAC,CAAC;QACjF,GAAG;QACH,GAAG,WAAW;QACd,GAAG,MAAM;QACT,aAAa,EAAE,oBAAoB,EAAE;QACrC,GAAG,EAAE,aAAa,EAAE;KACrB,CAAC,CAAC;IAEH,OAAO;QACL,iEAAiE;QACjE,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACjE,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACjE,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/D,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/D,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACjE,KAAK,EAAE,CAAC,WAAW,EAAE,EAAE,CACrB,iBAAiB,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,GAAG,WAAW,EAAE,GAAG,WAAW,EAAE,CAAC;KACpE,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,cAAc,EAAE,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,cAAc,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;YAC/C,OAAO,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,2BAA2B;QAC7B,CAAC;IACH,CAAC;IACD,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC"}

package/dist/singleton/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Register a singleton value under a given key.
+ * Convention: keys are `<pkg>:<purpose>` to avoid collisions (e.g. `hazo_core:context_als`).
+ *
+ * If the key is already registered, the existing value is returned unchanged and a warning
+ * is emitted — this operation is idempotent and never overwrites.
+ *
+ * @returns The registered value (either the new one or the pre-existing one)
+ */
+export declare function registerSingleton<T>(key: string, value: T): T;
+/**
+ * Retrieve a previously registered singleton value by key.
+ * Returns undefined if the key has never been registered.
+ */
+export declare function getSingleton<T>(key: string): T | undefined;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/singleton/index.ts"],"names":[],"mappings":"AAgBA;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAU7D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAM1D"}

package/dist/singleton/index.js

@@ -0,0 +1,42 @@
+import { HAZO_SINGLETONS_KEY } from '../constants.js';
+/**
+ * Gets or creates the singleton registry on globalThis.
+ * The registry lives on globalThis so it survives pathological duplicate hazo_core copies.
+ */
+function getRegistry() {
+    const g = globalThis;
+    if (!g[HAZO_SINGLETONS_KEY]) {
+        g[HAZO_SINGLETONS_KEY] = Object.create(null);
+    }
+    return g[HAZO_SINGLETONS_KEY];
+}
+/**
+ * Register a singleton value under a given key.
+ * Convention: keys are `<pkg>:<purpose>` to avoid collisions (e.g. `hazo_core:context_als`).
+ *
+ * If the key is already registered, the existing value is returned unchanged and a warning
+ * is emitted — this operation is idempotent and never overwrites.
+ *
+ * @returns The registered value (either the new one or the pre-existing one)
+ */
+export function registerSingleton(key, value) {
+    const registry = getRegistry();
+    if (Object.prototype.hasOwnProperty.call(registry, key)) {
+        console.warn(`[hazo_core] registerSingleton: key "${key}" is already registered — returning existing value.`);
+        return registry[key];
+    }
+    registry[key] = value;
+    return value;
+}
+/**
+ * Retrieve a previously registered singleton value by key.
+ * Returns undefined if the key has never been registered.
+ */
+export function getSingleton(key) {
+    const registry = getRegistry();
+    if (Object.prototype.hasOwnProperty.call(registry, key)) {
+        return registry[key];
+    }
+    return undefined;
+}
+//# sourceMappingURL=index.js.map

package/dist/singleton/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/singleton/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAItD;;;GAGG;AACH,SAAS,WAAW;IAClB,MAAM,CAAC,GAAG,UAAqC,CAAC;IAChD,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC,EAAE,CAAC;QAC5B,CAAC,CAAC,mBAAmB,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAsB,CAAC;IACpE,CAAC;IACD,OAAO,CAAC,CAAC,mBAAmB,CAAsB,CAAC;AACrD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAI,GAAW,EAAE,KAAQ;IACxD,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAC/B,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC;QACxD,OAAO,CAAC,IAAI,CACV,uCAAuC,GAAG,qDAAqD,CAChG,CAAC;QACF,OAAO,QAAQ,CAAC,GAAG,CAAM,CAAC;IAC5B,CAAC;IACD,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACtB,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAI,GAAW;IACzC,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAC/B,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC;QACxD,OAAO,QAAQ,CAAC,GAAG,CAAM,CAAC;IAC5B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/utils/dates.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure date formatting utilities.
+ *
+ * No React, no DOM, no browser-only APIs. Safe for Node.js and browser alike.
+ * `Intl.DateTimeFormat` (used by the 'locale' format) is a standard ECMAScript
+ * Internationalization API available in Node.js 12+ and all modern browsers.
+ *
+ * Note on SSR safety: the 'locale' format delegates to toLocaleDateString(), which
+ * picks up the server or client locale and may therefore produce different output
+ * on server vs browser. Prefer 'iso', 'dmy', or 'mdy' for SSR-safe rendering.
+ *
+ * Originally in hazo_collab_forms/src/utils/date_format.ts — moved here in hazo_core
+ * as a pure shared utility. hazo_collab_forms re-exports from 'hazo_core' for backward
+ * compatibility.
+ */
+/**
+ * Date format options for displaying dates.
+ *   'iso'    — YYYY-MM-DD (locale-independent, SSR-safe)
+ *   'dmy'    — DD/MM/YYYY
+ *   'mdy'    — MM/DD/YYYY
+ *   'locale' — Use environment locale (NOT SSR-safe; may cause hydration mismatch)
+ */
+export type DateFormat = 'iso' | 'dmy' | 'mdy' | 'locale';
+/**
+ * Default date format.
+ */
+export declare const DEFAULT_DATE_FORMAT: DateFormat;
+/**
+ * Format a date according to the specified format.
+ *
+ * @param date   - Date object, ISO string, or undefined/null
+ * @param format - Format type (iso, dmy, mdy, locale)
+ * @returns Formatted date string, or empty string if date is invalid/absent
+ */
+export declare function format_date(date: Date | string | undefined | null, format?: DateFormat): string;
+/**
+ * Format a date range according to the specified format.
+ *
+ * @param from   - Start date
+ * @param to     - End date
+ * @param format - Format type
+ * @returns Formatted date range string
+ */
+export declare function format_date_range(from: Date | string | undefined | null, to: Date | string | undefined | null, format?: DateFormat): string;
+//# sourceMappingURL=dates.d.ts.map

package/dist/utils/dates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dates.d.ts","sourceRoot":"","sources":["../../src/utils/dates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,UAAkB,CAAC;AAErD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,EACtC,MAAM,GAAE,UAAgC,GACvC,MAAM,CAsCR;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,EACtC,EAAE,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,EACpC,MAAM,GAAE,UAAgC,GACvC,MAAM,CAQR"}

package/dist/utils/dates.js

@@ -0,0 +1,79 @@
+/**
+ * Pure date formatting utilities.
+ *
+ * No React, no DOM, no browser-only APIs. Safe for Node.js and browser alike.
+ * `Intl.DateTimeFormat` (used by the 'locale' format) is a standard ECMAScript
+ * Internationalization API available in Node.js 12+ and all modern browsers.
+ *
+ * Note on SSR safety: the 'locale' format delegates to toLocaleDateString(), which
+ * picks up the server or client locale and may therefore produce different output
+ * on server vs browser. Prefer 'iso', 'dmy', or 'mdy' for SSR-safe rendering.
+ *
+ * Originally in hazo_collab_forms/src/utils/date_format.ts — moved here in hazo_core
+ * as a pure shared utility. hazo_collab_forms re-exports from 'hazo_core' for backward
+ * compatibility.
+ */
+/**
+ * Default date format.
+ */
+export const DEFAULT_DATE_FORMAT = 'iso';
+/**
+ * Format a date according to the specified format.
+ *
+ * @param date   - Date object, ISO string, or undefined/null
+ * @param format - Format type (iso, dmy, mdy, locale)
+ * @returns Formatted date string, or empty string if date is invalid/absent
+ */
+export function format_date(date, format = DEFAULT_DATE_FORMAT) {
+    if (!date)
+        return '';
+    // Parse date if string
+    let date_obj;
+    if (typeof date === 'string') {
+        // Add explicit time component to avoid timezone-shift issues with date-only strings
+        date_obj = new Date(date.includes('T') ? date : date + 'T00:00:00');
+    }
+    else {
+        date_obj = date;
+    }
+    // Validate date
+    if (isNaN(date_obj.getTime())) {
+        return typeof date === 'string' ? date : '';
+    }
+    const year = date_obj.getFullYear();
+    const month = String(date_obj.getMonth() + 1).padStart(2, '0');
+    const day = String(date_obj.getDate()).padStart(2, '0');
+    switch (format) {
+        case 'iso':
+            return `${year}-${month}-${day}`;
+        case 'dmy':
+            return `${day}/${month}/${year}`;
+        case 'mdy':
+            return `${month}/${day}/${year}`;
+        case 'locale':
+            // Uses environment locale — not SSR-safe (may cause hydration mismatch in Next.js)
+            return date_obj.toLocaleDateString();
+        default:
+            return `${year}-${month}-${day}`;
+    }
+}
+/**
+ * Format a date range according to the specified format.
+ *
+ * @param from   - Start date
+ * @param to     - End date
+ * @param format - Format type
+ * @returns Formatted date range string
+ */
+export function format_date_range(from, to, format = DEFAULT_DATE_FORMAT) {
+    const from_str = format_date(from, format);
+    const to_str = format_date(to, format);
+    if (from_str && to_str)
+        return `${from_str} - ${to_str}`;
+    if (from_str)
+        return `From ${from_str}`;
+    if (to_str)
+        return `To ${to_str}`;
+    return '';
+}
+//# sourceMappingURL=dates.js.map

package/dist/utils/dates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dates.js","sourceRoot":"","sources":["../../src/utils/dates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAWH;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAe,KAAK,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CACzB,IAAsC,EACtC,SAAqB,mBAAmB;IAExC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAErB,uBAAuB;IACvB,IAAI,QAAc,CAAC;IACnB,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,oFAAoF;QACpF,QAAQ,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,WAAW,CAAC,CAAC;IACtE,CAAC;SAAM,CAAC;QACN,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC;IAED,gBAAgB;IAChB,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QAC9B,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9C,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC/D,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAExD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,KAAK;YACR,OAAO,GAAG,IAAI,IAAI,KAAK,IAAI,GAAG,EAAE,CAAC;QAEnC,KAAK,KAAK;YACR,OAAO,GAAG,GAAG,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;QAEnC,KAAK,KAAK;YACR,OAAO,GAAG,KAAK,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;QAEnC,KAAK,QAAQ;YACX,mFAAmF;YACnF,OAAO,QAAQ,CAAC,kBAAkB,EAAE,CAAC;QAEvC;YACE,OAAO,GAAG,IAAI,IAAI,KAAK,IAAI,GAAG,EAAE,CAAC;IACrC,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAsC,EACtC,EAAoC,EACpC,SAAqB,mBAAmB;IAExC,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAEvC,IAAI,QAAQ,IAAI,MAAM;QAAE,OAAO,GAAG,QAAQ,MAAM,MAAM,EAAE,CAAC;IACzD,IAAI,QAAQ;QAAE,OAAO,QAAQ,QAAQ,EAAE,CAAC;IACxC,IAAI,MAAM;QAAE,OAAO,MAAM,MAAM,EAAE,CAAC;IAClC,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/utils/env.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns the current environment name.
+ * Resolution: HAZO_ENV ?? NODE_ENV ?? 'development'
+ * This is the single source of truth for environment resolution across all hazo_* packages.
+ */
+export declare function getCurrentEnv(): string;
+//# sourceMappingURL=env.d.ts.map

package/dist/utils/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/utils/env.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/utils/env.js

@@ -0,0 +1,9 @@
+/**
+ * Returns the current environment name.
+ * Resolution: HAZO_ENV ?? NODE_ENV ?? 'development'
+ * This is the single source of truth for environment resolution across all hazo_* packages.
+ */
+export function getCurrentEnv() {
+    return process.env['HAZO_ENV'] ?? process.env['NODE_ENV'] ?? 'development';
+}
+//# sourceMappingURL=env.js.map

package/dist/utils/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/utils/env.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,aAAa,CAAC;AAC7E,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,69 @@
+export { getCurrentEnv } from './env.js';
+/**
+ * Generate a new request/correlation ID.
+ * Format: 'req_' + UUID v7 (time-ordered, sortable in logs and DB indexes).
+ * Per D-001 and D-006.
+ */
+export declare function generateRequestId(): string;
+/**
+ * Attempt a dynamic import of `pkg`. Returns null if the package is not
+ * installed or fails to load for any reason.
+ *
+ * Useful for optional peer dependencies that provide enhanced behavior when
+ * present but are not required.
+ */
+export declare function optional_import<T>(pkg: string): Promise<T | null>;
+/**
+ * JSON.parse that returns null instead of throwing on malformed input.
+ */
+export declare function safeJsonParse<T = unknown>(json: string): T | null;
+/**
+ * Promise-based delay. Useful in tests and retry loops.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Format a byte count into a human-readable string.
+ * @example formatBytes(1536) → "1.5 KB"
+ * @example formatBytes(1073741824) → "1 GB"
+ */
+export declare function formatBytes(bytes: number, decimals?: number): string;
+export { format_date, format_date_range, DEFAULT_DATE_FORMAT, } from './dates.js';
+export type { DateFormat } from './dates.js';
+/**
+ * Format a date as "28 May 2026"
+ */
+export declare function formatDateShort(date: Date | string): string;
+/**
+ * Format a date as "Wednesday, 28 May 2026"
+ */
+export declare function formatDateLong(date: Date | string): string;
+/**
+ * Format a date as "28/05/2026"
+ */
+export declare function formatDateSlash(date: Date | string): string;
+/**
+ * Format a number as currency.
+ * @example formatCurrency(1234.56) → "$1,234.56"
+ * @example formatCurrency(1234.56, 'GBP') → "£1,234.56"
+ */
+export declare function formatCurrency(amount: number, currency?: string): string;
+/**
+ * Format a number with optional decimal places.
+ * @example formatNumber(1234567.89) → "1,234,567.89"
+ * @example formatNumber(1234567.89, 0) → "1,234,568"
+ */
+export declare function formatNumber(n: number, decimals?: number): string;
+/**
+ * Format a boolean as a human-readable string.
+ * @example formatBoolean(true) → "Yes"
+ * @example formatBoolean(false) → "No"
+ */
+export declare function formatBoolean(val: boolean): string;
+/**
+ * Extract initials from a name.
+ * @example getInitials('John Doe') → 'JD'
+ * @example getInitials('Alice') → 'A'
+ * @example getInitials('Mary Jane Watson') → 'MJW'
+ */
+export declare function getInitials(name: string): string;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAMzC;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAMD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAMvE;AAMD;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAMjE;AAMD;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAMD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAW/D;AAMD,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAU7C;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAO3D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAQ1D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAM3D;AAMD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,SAAQ,GAAG,MAAM,CAOvE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAKjE;AAMD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAElD;AAMD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOhD"}