hanzio 3.0.0 → 3.1.0

package/dist/src/zod/index.js

@@ -1,261 +1,24 @@
+import {
+  zodToTypeString2,
+  zodToExample2,
+  unwrapSchema2,
+  getEnumValues2,
+  getObjectShape2,
+  zodDefaults2
+} from "../../index-ww09bm49.js";
 import {
   toArray2
-} from "../../index-hy7kbb99.js";
+} from "../../index-5tzqfmnj.js";
 import {
   ok2,
   err2
-} from "../../index-0zvtcbzy.js";
+} from "../../index-6f2w90pp.js";
 import {
   isRecord2
 } from "../../index-8r2vdzjg.js";
 
 // src/zod/index.ts
 import { z as z3 } from "zod";
-
-// src/zod/zodToTypeString.ts
-var visiting = new Set;
-function walk(schema, onCycle, fn) {
-  if (visiting.has(schema))
-    return onCycle;
-  visiting.add(schema);
-  try {
-    return fn(defOf(schema));
-  } finally {
-    visiting.delete(schema);
-  }
-}
-function defOf(schema) {
-  return schema._zod.def;
-}
-function pipeTarget(def) {
-  return defOf(def.out).type === "transform" ? def.in : def.out;
-}
-function literal(value) {
-  if (typeof value === "string")
-    return JSON.stringify(value);
-  return typeof value === "bigint" ? `${value}n` : String(value);
-}
-function wrap(type) {
-  return /[|&]/.test(type) ? `(${type})` : type;
-}
-function zodToTypeString(schema, indent = 0) {
-  return walk(schema, "unknown", (def) => {
-    const pad = "  ".repeat(indent);
-    const innerPad = "  ".repeat(indent + 1);
-    const render = (inner) => zodToTypeString(inner, indent);
-    switch (def.type) {
-      case "object": {
-        const entries = Object.entries(def.shape);
-        if (entries.length === 0)
-          return "{}";
-        const fields = entries.map(([key, value]) => {
-          const valueDef = defOf(value);
-          const isOptional = valueDef.type === "optional";
-          const typeStr = zodToTypeString(isOptional ? valueDef.innerType : value, indent + 1);
-          return `${innerPad}${key}${isOptional ? "?" : ""}: ${typeStr}`;
-        });
-        return `{
-${fields.join(`
-`)}
-${pad}}`;
-      }
-      case "array":
-        return `${wrap(render(def.element))}[]`;
-      case "tuple": {
-        const items = def.items.map(render);
-        if (def.rest)
-          items.push(`...${wrap(render(def.rest))}[]`);
-        return `[${items.join(", ")}]`;
-      }
-      case "string":
-      case "number":
-      case "bigint":
-      case "boolean":
-      case "symbol":
-      case "null":
-      case "undefined":
-      case "void":
-      case "never":
-      case "any":
-      case "unknown":
-        return def.type;
-      case "date":
-        return "Date";
-      case "record":
-        return `Record<${render(def.keyType)}, ${render(def.valueType)}>`;
-      case "map":
-        return `Map<${render(def.keyType)}, ${render(def.valueType)}>`;
-      case "set":
-        return `Set<${render(def.valueType)}>`;
-      case "promise":
-        return `Promise<${render(def.innerType)}>`;
-      case "enum":
-        return Object.values(def.entries).map(literal).join(" | ");
-      case "literal":
-        return def.values.map(literal).join(" | ");
-      case "union":
-        return def.options.map(render).join(" | ");
-      case "intersection":
-        return `${wrap(render(def.left))} & ${wrap(render(def.right))}`;
-      case "optional":
-        return `${render(def.innerType)} | undefined`;
-      case "nullable":
-        return `${render(def.innerType)} | null`;
-      case "nonoptional": {
-        const innerDef = defOf(def.innerType);
-        return render(innerDef.type === "optional" ? innerDef.innerType : def.innerType);
-      }
-      case "default":
-      case "prefault":
-      case "catch":
-      case "readonly":
-        return render(def.innerType);
-      case "lazy":
-        return render(def.getter());
-      case "pipe":
-        return render(pipeTarget(def));
-      default:
-        return "unknown";
-    }
-  });
-}
-function zodToExample(schema) {
-  return walk(schema, null, (def) => {
-    switch (def.type) {
-      case "object": {
-        const result = {};
-        for (const [key, value] of Object.entries(def.shape)) {
-          if (defOf(value).type !== "optional") {
-            result[key] = zodToExample(value);
-          }
-        }
-        return result;
-      }
-      case "array":
-        return [zodToExample(def.element)];
-      case "set":
-        return [zodToExample(def.valueType)];
-      case "tuple":
-        return def.items.map(zodToExample);
-      case "string":
-        return "";
-      case "number":
-      case "bigint":
-        return 0;
-      case "boolean":
-        return false;
-      case "date":
-        return new Date(0).toISOString();
-      case "enum":
-        return Object.values(def.entries)[0];
-      case "literal":
-        return def.values[0];
-      case "union":
-        return zodToExample(def.options[0]);
-      case "intersection": {
-        const left = zodToExample(def.left);
-        const right = zodToExample(def.right);
-        return isRecord2(left) && isRecord2(right) ? { ...left, ...right } : left;
-      }
-      case "optional":
-      case "nullable":
-      case "nonoptional":
-      case "default":
-      case "prefault":
-      case "catch":
-      case "readonly":
-      case "promise":
-        return zodToExample(def.innerType);
-      case "lazy":
-        return zodToExample(def.getter());
-      case "pipe":
-        return zodToExample(pipeTarget(def));
-      case "record":
-      case "map":
-        return {};
-      default:
-        return null;
-    }
-  });
-}
-
-// src/zod/introspect.ts
-function pipeInput(def) {
-  return defOf(def.in).type === "transform" ? def.out : def.in;
-}
-function unwrapOnce(def) {
-  switch (def.type) {
-    case "optional":
-    case "nullable":
-    case "default":
-    case "prefault":
-    case "nonoptional":
-    case "catch":
-    case "readonly":
-      return def.innerType;
-    case "lazy":
-      return def.getter();
-    case "pipe":
-      return pipeInput(def);
-    default:
-      return;
-  }
-}
-function unwrapSchema(schema) {
-  const inner = unwrapOnce(defOf(schema));
-  return inner ? unwrapSchema(inner) : schema;
-}
-function getEnumValues(schema) {
-  const def = defOf(unwrapSchema(schema));
-  return def.type === "enum" ? Object.values(def.entries).map(String) : undefined;
-}
-function getObjectShape(schema) {
-  const def = defOf(unwrapSchema(schema));
-  return def.type === "object" ? def.shape : undefined;
-}
-function zodDefaults(schema) {
-  return defaultFor(schema);
-}
-function defaultFor(schema) {
-  return walk(schema, undefined, (def) => {
-    switch (def.type) {
-      case "default":
-      case "prefault":
-        return def.defaultValue;
-      case "optional":
-        return;
-      case "nullable":
-        return null;
-      case "object": {
-        const result = {};
-        for (const [key, child] of Object.entries(def.shape)) {
-          result[key] = defaultFor(child);
-        }
-        return result;
-      }
-      case "array":
-        return [];
-      case "string":
-        return "";
-      case "number":
-        return 0;
-      case "bigint":
-        return 0n;
-      case "boolean":
-        return false;
-      case "enum":
-        return Object.values(def.entries)[0];
-      case "literal":
-        return def.values[0];
-      case "union":
-        return def.options[0] && defaultFor(def.options[0]);
-      default: {
-        const inner = unwrapOnce(def);
-        return inner && defaultFor(inner);
-      }
-    }
-  });
-}
 // src/zod/jsonToZodSchemaMapper.ts
 import { z } from "zod";
 function jsonToZodSchemaMapper(jsonObject, zodSchema, config) {
@@ -342,6 +105,8 @@ var zJsonValue = z3.lazy(() => z3.union([
   zJsonObject
 ]));
 var zJsonObject = z3.record(z3.string(), zJsonValue);
+var E164_REGEX = /^\+[1-9]\d{6,14}$/;
+var zOptionalE164 = z3.string().refine((value) => value === "" || E164_REGEX.test(value), "Phone number must be in E.164 format (e.g. +14155551234)").describe("E.164 phone number (e.g. +14155551234); empty string clears it").nullable().transform((value) => value || null);
 function parseJson(text, schema) {
   let value;
   try {
@@ -359,12 +124,13 @@ function zSingleOrArray(schema) {
 }
 var normalizeSingleOrArray = toArray2;
 export {
+  E164_REGEX,
   asId,
   createIdHelpers,
   createMinMaxFilter,
   createZId,
-  getEnumValues,
-  getObjectShape,
+  getEnumValues2 as getEnumValues,
+  getObjectShape2 as getObjectShape,
   jsonToZodSchemaMapper,
   normalizeSingleOrArray,
   parseId,
@@ -372,12 +138,13 @@ export {
   safeParseId,
   toGtLtFilter,
   toGteLteFilter,
-  unwrapSchema,
+  unwrapSchema2 as unwrapSchema,
   zJsonObject,
   zJsonValue,
+  zOptionalE164,
   zSingleOrArray,
-  zodDefaults,
+  zodDefaults2 as zodDefaults,
   zodMinMaxFilter,
-  zodToExample,
-  zodToTypeString
+  zodToExample2 as zodToExample,
+  zodToTypeString2 as zodToTypeString
 };

package/dist/string/index.d.ts

@@ -79,3 +79,24 @@ export declare function initials(name: string | null | undefined, options?: {
 }): string;
 /** `JSON.parse` that returns a `Result` instead of throwing. */
 export declare function safeJsonParse<T = unknown>(text: string): Result<T, SyntaxError>;
+/** Escapes `& < > " '` for HTML or XML text and attribute values. */
+export declare function escapeHtml(text: string): string;
+/**
+ * Removes emoji and tidies the spacing they leave, so `'Hi there 👋, welcome'`
+ * becomes `'Hi there, welcome'`. Use it for text that is spoken (TTS drops
+ * emoji from the audio but not from the transcript). Text without emoji is
+ * returned unchanged.
+ */
+export declare function stripEmoji(text: string): string;
+/**
+ * Lowercased extension of a file name or path, without the dot. `undefined`
+ * when there is none; like `path.extname`, a leading dot (`.env`) is not one.
+ */
+export declare function fileExtension(filename: string): string | undefined;
+/**
+ * Normalizes a value the way a JSON round trip does: `undefined` properties
+ * are dropped, `Date`s become ISO strings and `NaN` becomes `null`. Top-level
+ * `undefined` becomes `null`. Use it before storing loosely typed data in a
+ * JSON column. Throws on `bigint` and circular references.
+ */
+export declare function toJsonValue(value: unknown): JsonValue;

package/dist/testing/connection-auth-contract.d.ts

@@ -0,0 +1,43 @@
+export type ConnectionAuthContractInput = {
+    reset: () => void;
+    create: (fetchImpl: typeof fetch, variant?: string) => {
+        read: () => Promise<unknown>;
+        login: (options?: {
+            signal?: AbortSignal;
+        }) => Promise<string>;
+    };
+    identityChanges: string[];
+    isLogin: (url: string) => boolean;
+    loginResponse: (token: string) => Response;
+    readResponse: () => Response;
+    tokenHeader: string;
+};
+/**
+ * Registers the races every client built on `ConnectionAuthCache`
+ * (`hanzio/api-wrapper/connection-auth`) must survive, run through the real
+ * client and its transport: shared refreshes, rotated credentials, late 401s,
+ * aborted waiters and failed fresh logins. Await it at the top level of a
+ * `bun:test` file.
+ *
+ * - `create(fetch, variant)` builds a client on the given fetch. `variant` is
+ *   one of `identityChanges` (a credential change that must force a new login),
+ *   `'settings'` (a non-auth setting that must reuse the login), `'connection'`
+ *   (another connection) or `'secret'` (a rotated secret).
+ * - `read()` makes one authenticated request; on a 401 it calls `reject` and
+ *   retries once. `login()` forces a fresh login and resolves its token.
+ * - `reset()` clears the cache between tests.
+ * - `tokenHeader` is where requests carry the token; `'authorization'` means
+ *   `Bearer <token>`.
+ *
+ * @example
+ * await connectionAuthContract({
+ *   reset: () => authCache.clear(),
+ *   create: (fetch, variant) => new ShopApi(credentialsFor(variant), fetch),
+ *   identityChanges: ['apiKey', 'secret'],
+ *   isLogin: (url) => url.endsWith('/oauth/token'),
+ *   loginResponse: (token) => Response.json({ access_token: token, expires_in: 3600 }),
+ *   readResponse: () => Response.json({ items: [] }),
+ *   tokenHeader: 'authorization'
+ * })
+ */
+export declare function connectionAuthContract(input: ConnectionAuthContractInput): Promise<void>;

package/dist/testing/helpers.d.ts

@@ -0,0 +1,26 @@
+type LogMethod = (...args: unknown[]) => void;
+export type NoopLogger = {
+    trace: LogMethod;
+    debug: LogMethod;
+    info: LogMethod;
+    warn: LogMethod;
+    error: LogMethod;
+    fatal: LogMethod;
+    bind: (...args: unknown[]) => NoopLogger;
+    child: (...args: unknown[]) => NoopLogger;
+};
+/** A logger that discards everything; `bind` and `child` return itself. */
+export declare const noopLogger: NoopLogger;
+/**
+ * Reads one argument from a mock's call history as `T`. Bun types
+ * `mock.calls` as `never[]` for loosely typed mocks.
+ *
+ * @example
+ * const input = mockCallArg<CreateUserInput>(createUser) // first call, first argument
+ */
+export declare function mockCallArg<T>(fn: {
+    mock: {
+        calls: unknown[][];
+    };
+}, callIndex?: number, argIndex?: number): T;
+export {};

package/dist/testing/index.d.ts

@@ -0,0 +1,5 @@
+export { type ConnectionAuthContractInput, connectionAuthContract } from './connection-auth-contract';
+export { mockCallArg, type NoopLogger, noopLogger } from './helpers';
+export { ModuleMocker } from './module-mocker';
+export { createPrismaMock, type DeepMockedPrisma, type PrismaMethodMock } from './prisma';
+export { createTestStorage, installWindowShim } from './window';

package/dist/testing/module-mocker.d.ts

@@ -0,0 +1,30 @@
+type ModuleExports = Record<string, unknown>;
+/**
+ * `mock.module` that can be undone. Bun replaces a mocked module for the whole
+ * process and `mock.restore()` does not bring it back
+ * (https://github.com/oven-sh/bun/issues/7823), so one suite's stub silently
+ * leaks into every later suite.
+ *
+ * Mocks spread the module's real exports first, so exports you don't override
+ * keep working, and `clear()` re-registers the originals. Call it in
+ * `afterEach` or `afterAll`.
+ *
+ * Bun resolves specifiers relative to the file that registers the mock, so
+ * pass absolute paths or package names. A `resolve` function maps your own
+ * shorthand (an `@/` alias, a source-root-relative path) to absolute paths.
+ *
+ * @example
+ * const moduleMocker = new ModuleMocker((specifier) =>
+ *   specifier.startsWith('@/') ? path.resolve(srcDir, specifier.slice(2)) : specifier
+ * )
+ * await moduleMocker.mock('@/lib/posthog', () => ({ captureException: mock() }))
+ * afterAll(() => moduleMocker.clear())
+ */
+export declare class ModuleMocker {
+    private readonly resolve;
+    private restorers;
+    constructor(resolve?: (specifier: string) => string);
+    mock(specifier: string, renderMocks: () => ModuleExports): Promise<void>;
+    clear(): void;
+}
+export {};

package/dist/testing/prisma.d.ts

@@ -0,0 +1,30 @@
+import type { Mock, mock } from 'bun:test';
+export type PrismaMethodMock = Mock<(...args: unknown[]) => Promise<unknown>>;
+/**
+ * A Prisma client where every model delegate and every method is a Bun mock,
+ * created on first access, like `jest-mock-extended`'s `mockDeep()`.
+ * `$`-prefixed client methods (`$transaction`, `$queryRaw`) are mocks too.
+ */
+export type DeepMockedPrisma<Client> = {
+    [K in keyof Client]: Client[K] extends (...args: never[]) => unknown ? PrismaMethodMock : {
+        [Method in keyof Client[K]]: PrismaMethodMock;
+    };
+} & {
+    /** Resets every mock created so far. Call it in `beforeEach`. */
+    $reset: () => void;
+};
+/**
+ * Builds a deep auto-mock of a Prisma client from Bun's `mock`. Register it
+ * with `mock.module` in place of the module that exports your client.
+ *
+ * @example
+ * import { mock } from 'bun:test'
+ * import type { prisma } from '../lib/prisma'
+ *
+ * export const prismaMock = createPrismaMock<typeof prisma>(mock)
+ * mock.module(prismaModulePath, () => ({ ...prismaExports, prisma: prismaMock }))
+ *
+ * prismaMock.user.findUnique.mockResolvedValue({ id: 'u1' })
+ * expect(prismaMock.user.findUnique).toHaveBeenCalledWith({ where: { id: 'u1' } })
+ */
+export declare function createPrismaMock<Client>(createMock: typeof mock): DeepMockedPrisma<Client>;

package/dist/testing/window.d.ts

@@ -0,0 +1,18 @@
+/** A complete in-memory `Storage` (`localStorage` / `sessionStorage`). */
+export declare function createTestStorage(): Storage;
+/**
+ * Installs a minimal `globalThis.window` for unit tests of browser-facing code
+ * that only probes `window` (`location`, `localStorage`, event listeners), and
+ * returns a `reset` to call in `afterEach`.
+ *
+ * Tests may assign a partial `window`. The shim keeps its own shape and copies
+ * `location`, `localStorage` and the listener functions from the assigned
+ * object, because libraries such as axios and PostHog read those at import
+ * time. It installs no `document`: Vue and PrismJS treat one as a full DOM.
+ *
+ * @example
+ * // test-setup.ts, preloaded through bunfig.toml
+ * const resetWindow = installWindowShim()
+ * afterEach(resetWindow)
+ */
+export declare function installWindowShim(href?: string): () => void;

package/dist/zod/index.d.ts

@@ -30,6 +30,16 @@ export declare function createIdHelpers<TypeNames extends string>(): {
 /** Any JSON value (no `undefined`, `NaN` or `Infinity`). */
 export declare const zJsonValue: z.ZodType<JsonValue>;
 export declare const zJsonObject: z.ZodType<JsonObject>;
+/** An E.164 phone number: `+`, then 7 to 15 digits with no leading zero. */
+export declare const E164_REGEX: RegExp;
+/**
+ * An optional E.164 phone number for forms: a cleared input submits `''`,
+ * which means "no number", so `''` and `null` both parse to `null`.
+ *
+ * Deliberately not `union([regex, literal('')])`: that serializes the empty
+ * literal as `enum: [""]`, which Gemini function declarations reject.
+ */
+export declare const zOptionalE164: z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | null, string | null>>;
 /** `JSON.parse` + `schema.safeParse` without throwing. */
 export declare function parseJson<S extends z.ZodType>(text: string, schema: S): Result<z.output<S>, SyntaxError | z.ZodError>;
 export declare function zSingleOrArray<T extends z.ZodType>(schema: T): z.ZodUnion<readonly [z.ZodArray<T>, T]>;

package/dist/zod/introspect.d.ts

@@ -1,5 +1,6 @@
 import type { z } from 'zod';
-import { type Schema } from './zodToTypeString';
+import { type Def, type Schema } from './zodToTypeString';
+export declare function unwrapOnce(def: Def): Schema | undefined;
 /**
  * Strips optional/nullable/default/prefault/nonoptional/catch/readonly/lazy
  * wrappers and pipes (input side) until the schema that carries the shape.