@ontrails/core 1.0.0-beta.0

package/dist/validate-topo.js

@@ -0,0 +1,108 @@
+/**
+ * Structural validation for a Topo graph.
+ *
+ * Checks hike follows references, example input validity, event origin
+ * references, and output schema completeness. Returns a Result with all
+ * issues collected into a single ValidationError.
+ */
+import { ValidationError } from './errors.js';
+import { Result } from './result.js';
+import { validateInput } from './validation.js';
+// ---------------------------------------------------------------------------
+// Validators
+// ---------------------------------------------------------------------------
+const checkFollows = (hikes, topo) => {
+    const issues = [];
+    for (const [id, hike] of hikes) {
+        for (const followId of hike.follows) {
+            if (followId === id) {
+                issues.push({
+                    message: `Hike follows itself`,
+                    rule: 'no-self-follow',
+                    trailId: id,
+                });
+            }
+            else if (!topo.has(followId)) {
+                issues.push({
+                    message: `Follows "${followId}" which is not in the topo`,
+                    rule: 'follows-exist',
+                    trailId: id,
+                });
+            }
+        }
+    }
+    return issues;
+};
+const checkOneExample = (id, example, inputSchema, hasOutput) => {
+    const issues = [];
+    const result = validateInput(inputSchema, example.input);
+    if (result.isErr() && example.error === undefined) {
+        issues.push({
+            message: `Example "${example.name}" input does not parse against schema`,
+            rule: 'example-input-valid',
+            trailId: id,
+        });
+    }
+    if (example.expected !== undefined && !hasOutput) {
+        issues.push({
+            message: `Example "${example.name}" has expected output but trail has no output schema`,
+            rule: 'output-schema-present',
+            trailId: id,
+        });
+    }
+    return issues;
+};
+const checkExamples = (trails) => {
+    const issues = [];
+    for (const [id, trail] of trails) {
+        if (!trail.examples) {
+            continue;
+        }
+        for (const example of trail.examples) {
+            issues.push(...checkOneExample(id, example, trail.input, !!trail.output));
+        }
+    }
+    return issues;
+};
+const checkEventOrigins = (events, topo) => {
+    const issues = [];
+    for (const [id, evt] of events) {
+        if (!evt.from) {
+            continue;
+        }
+        for (const originId of evt.from) {
+            if (!topo.has(originId)) {
+                issues.push({
+                    message: `Event origin "${originId}" is not in the topo`,
+                    rule: 'event-origin-exists',
+                    trailId: id,
+                });
+            }
+        }
+    }
+    return issues;
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Validate the structural integrity of a Topo graph.
+ *
+ * Checks follows references, example inputs, event origins, and output
+ * schema presence. Returns `Result.ok()` when no issues are found, or
+ * `Result.err(ValidationError)` with all issues in the error context.
+ */
+export const validateTopo = (topo) => {
+    const issues = [
+        ...checkFollows(topo.hikes, topo),
+        ...checkExamples(topo.trails),
+        ...checkEventOrigins(topo.events, topo),
+    ];
+    if (issues.length === 0) {
+        return Result.ok();
+    }
+    return Result.err(new ValidationError(`Topo validation failed with ${issues.length} issue(s)`, {
+        context: { issues },
+    }));
+};
+//# sourceMappingURL=validate-topo.js.map

package/dist/validate-topo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-topo.js","sourceRoot":"","sources":["../src/validate-topo.ts"],"names":[],"mappings":"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"}

package/dist/validation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Validation utilities for @ontrails/core
+ *
+ * Wraps Zod parsing into Result types and provides JSON Schema conversion
+ * for trail input schemas.
+ */
+import type { z } from 'zod';
+import { ValidationError } from './errors.js';
+import { Result } from './result.js';
+type JsonSchema = Record<string, unknown>;
+type JsonSchemaConverter = (schema: z.ZodType) => JsonSchema;
+/** Format each ZodIssue as "path: message" (or just "message" for root). */
+export declare const formatZodIssues: (issues: z.ZodIssue[]) => string[];
+/** Parse unknown data against a Zod schema, returning a Result. */
+export declare const validateInput: <T>(schema: z.ZodType<T>, data: unknown) => Result<T, ValidationError>;
+/** Parse unknown data against a Zod schema, returning a Result suitable for output validation. */
+export declare const validateOutput: <T>(schema: z.ZodType<T>, data: unknown) => Result<T, ValidationError>;
+/**
+ * Convert common Zod types to a JSON Schema object.
+ *
+ * Uses Zod v4's `_zod.def` and `_zod.traits` for introspection.
+ * Covers: string, number, boolean, object, array, enum, optional,
+ * default, union, literal, nullable, and describe.
+ */
+export declare const zodToJsonSchema: JsonSchemaConverter;
+export {};
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAerC,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC1C,KAAK,mBAAmB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,KAAK,UAAU,CAAC;AAe7D,4EAA4E;AAC5E,eAAO,MAAM,eAAe,GAAI,QAAQ,CAAC,CAAC,QAAQ,EAAE,KAAG,MAAM,EAIzD,CAAC;AAML,mEAAmE;AACnE,eAAO,MAAM,aAAa,GAAI,CAAC,EAC7B,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,OAAO,KACZ,MAAM,CAAC,CAAC,EAAE,eAAe,CAY3B,CAAC;AAMF,kGAAkG;AAClG,eAAO,MAAM,cAAc,GAAI,CAAC,EAC9B,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,OAAO,KACZ,MAAM,CAAC,CAAC,EAAE,eAAe,CAY3B,CAAC;AAMF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,mBA8E7B,CAAC"}

package/dist/validation.js

@@ -0,0 +1,134 @@
+/**
+ * Validation utilities for @ontrails/core
+ *
+ * Wraps Zod parsing into Result types and provides JSON Schema conversion
+ * for trail input schemas.
+ */
+import { ValidationError } from './errors.js';
+import { Result } from './result.js';
+// ---------------------------------------------------------------------------
+// Internal helpers (defined before usage)
+// ---------------------------------------------------------------------------
+const isOptionalLike = (s) => {
+    const defType = s._zod.def['type'];
+    return defType === 'optional' || defType === 'default';
+};
+// ---------------------------------------------------------------------------
+// Issue formatting
+// ---------------------------------------------------------------------------
+/** Format each ZodIssue as "path: message" (or just "message" for root). */
+export const formatZodIssues = (issues) => issues.map((issue) => {
+    const path = issue.path.join('.');
+    return path ? `${path}: ${issue.message}` : issue.message;
+});
+// ---------------------------------------------------------------------------
+// Input validation
+// ---------------------------------------------------------------------------
+/** Parse unknown data against a Zod schema, returning a Result. */
+export const validateInput = (schema, data) => {
+    const parsed = schema.safeParse(data);
+    if (parsed.success) {
+        return Result.ok(parsed.data);
+    }
+    const messages = formatZodIssues(parsed.error.issues);
+    return Result.err(new ValidationError(messages.join('; '), {
+        cause: parsed.error,
+        context: { issues: parsed.error.issues },
+    }));
+};
+// ---------------------------------------------------------------------------
+// Output validation
+// ---------------------------------------------------------------------------
+/** Parse unknown data against a Zod schema, returning a Result suitable for output validation. */
+export const validateOutput = (schema, data) => {
+    const parsed = schema.safeParse(data);
+    if (parsed.success) {
+        return Result.ok(parsed.data);
+    }
+    const messages = formatZodIssues(parsed.error.issues);
+    return Result.err(new ValidationError(`Output validation failed: ${messages.join('; ')}`, {
+        cause: parsed.error,
+        context: { issues: parsed.error.issues },
+    }));
+};
+// ---------------------------------------------------------------------------
+// Zod → JSON Schema (public API)
+// ---------------------------------------------------------------------------
+/**
+ * Convert common Zod types to a JSON Schema object.
+ *
+ * Uses Zod v4's `_zod.def` and `_zod.traits` for introspection.
+ * Covers: string, number, boolean, object, array, enum, optional,
+ * default, union, literal, nullable, and describe.
+ */
+export const zodToJsonSchema = (schema) => {
+    const s = schema;
+    const collectObjectFields = (shape) => {
+        const properties = {};
+        const required = [];
+        for (const [key, value] of Object.entries(shape)) {
+            properties[key] = zodToJsonSchema(value);
+            if (!isOptionalLike(value)) {
+                required.push(key);
+            }
+        }
+        return { properties, required };
+    };
+    const convertObject = (value) => {
+        const shape = value._zod.def['shape'];
+        if (!shape) {
+            return { type: 'object' };
+        }
+        const { properties, required } = collectObjectFields(shape);
+        const result = { properties, type: 'object' };
+        if (required.length > 0) {
+            result['required'] = required;
+        }
+        return result;
+    };
+    const zodConverters = {
+        array: (value) => {
+            const element = value._zod.def['element'];
+            return { items: zodToJsonSchema(element), type: 'array' };
+        },
+        boolean: () => ({ type: 'boolean' }),
+        default: (value) => {
+            const inner = value._zod.def['innerType'];
+            const innerSchema = zodToJsonSchema(inner);
+            const rawDefault = value._zod.def['defaultValue'];
+            innerSchema['default'] =
+                typeof rawDefault === 'function' ? rawDefault() : rawDefault;
+            return innerSchema;
+        },
+        enum: (value) => {
+            const entries = value._zod.def['entries'];
+            return { enum: Object.values(entries), type: 'string' };
+        },
+        literal: (value) => {
+            const values = value._zod.def['values'];
+            return { const: values[0] };
+        },
+        nullable: (value) => {
+            const inner = value._zod.def['innerType'];
+            return { anyOf: [zodToJsonSchema(inner), { type: 'null' }] };
+        },
+        number: () => ({ type: 'number' }),
+        object: convertObject,
+        optional: (value) => {
+            const inner = value._zod.def['innerType'];
+            return zodToJsonSchema(inner);
+        },
+        string: () => ({ type: 'string' }),
+        union: (value) => {
+            const options = value._zod.def['options'];
+            return { anyOf: options.map((option) => zodToJsonSchema(option)) };
+        },
+    };
+    const converter = zodConverters[s._zod.def['type']];
+    const base = converter ? converter(s) : {};
+    if (s.description) {
+        base['description'] = s.description;
+    }
+    return base;
+};
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}

package/dist/workspace.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Workspace detection utilities.
+ *
+ * Walks the filesystem to find monorepo workspace roots and provides
+ * helpers for working with paths relative to a workspace.
+ */
+import { NotFoundError } from './errors.js';
+import { Result } from './result.js';
+/**
+ * Walks up from `startDir` (defaults to `process.cwd()`) looking for a
+ * `package.json` that contains a `"workspaces"` field.
+ *
+ * Returns the directory path of the workspace root on success, or a
+ * `NotFoundError` if no workspace root is found.
+ */
+export declare const findWorkspaceRoot: (startDir?: string) => Promise<Result<string, NotFoundError>>;
+/**
+ * Returns `true` if `filePath` is inside `workspaceRoot`.
+ */
+export declare const isInsideWorkspace: (filePath: string, workspaceRoot: string) => boolean;
+/**
+ * Returns the relative path from `workspaceRoot` to `filePath`.
+ */
+export declare const getRelativePath: (filePath: string, workspaceRoot: string) => string;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAiBrC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,WAAW,MAAM,KAChB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAqBvC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAC5B,UAAU,MAAM,EAChB,eAAe,MAAM,KACpB,OAGF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,MAAM,EAChB,eAAe,MAAM,KACpB,MAA6D,CAAC"}

package/dist/workspace.js

@@ -0,0 +1,57 @@
+/**
+ * Workspace detection utilities.
+ *
+ * Walks the filesystem to find monorepo workspace roots and provides
+ * helpers for working with paths relative to a workspace.
+ */
+import { resolve, relative, dirname, join, isAbsolute } from 'node:path';
+import { NotFoundError } from './errors.js';
+import { Result } from './result.js';
+/** Check if a directory has a package.json with a `workspaces` field. */
+const hasWorkspacesField = async (dir) => {
+    const pkgPath = join(dir, 'package.json');
+    const file = Bun.file(pkgPath);
+    if (!(await file.exists())) {
+        return false;
+    }
+    try {
+        const pkg = await file.json();
+        return typeof pkg === 'object' && pkg !== null && 'workspaces' in pkg;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Walks up from `startDir` (defaults to `process.cwd()`) looking for a
+ * `package.json` that contains a `"workspaces"` field.
+ *
+ * Returns the directory path of the workspace root on success, or a
+ * `NotFoundError` if no workspace root is found.
+ */
+export const findWorkspaceRoot = async (startDir) => {
+    let current = resolve(startDir ?? process.cwd());
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        if (await hasWorkspacesField(current)) {
+            return Result.ok(current);
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return Result.err(new NotFoundError(`No workspace root found from "${startDir ?? process.cwd()}"`));
+        }
+        current = parent;
+    }
+};
+/**
+ * Returns `true` if `filePath` is inside `workspaceRoot`.
+ */
+export const isInsideWorkspace = (filePath, workspaceRoot) => {
+    const rel = relative(resolve(workspaceRoot), resolve(filePath));
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+};
+/**
+ * Returns the relative path from `workspaceRoot` to `filePath`.
+ */
+export const getRelativePath = (filePath, workspaceRoot) => relative(resolve(workspaceRoot), resolve(filePath));
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,yEAAyE;AACzE,MAAM,kBAAkB,GAAG,KAAK,EAAE,GAAW,EAAoB,EAAE;IACjE,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAY,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QACvC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,YAAY,IAAI,GAAG,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EACpC,QAAiB,EACuB,EAAE;IAC1C,IAAI,OAAO,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAEjD,iDAAiD;IACjD,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,MAAM,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,OAAO,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;QAC5B,CAAC;QAED,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAEhC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,OAAO,MAAM,CAAC,GAAG,CACf,IAAI,aAAa,CACf,iCAAiC,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE,GAAG,CAC9D,CACF,CAAC;QACJ,CAAC;QAED,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;AACH,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,QAAgB,EAChB,aAAqB,EACZ,EAAE;IACX,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChE,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACjE,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,QAAgB,EAChB,aAAqB,EACb,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@ontrails/core",
+  "version": "1.0.0-beta.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./patterns": "./src/patterns/index.ts",
+    "./redaction": "./src/redaction/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "peerDependencies": {
+    "zod": "catalog:"
+  }
+}

package/src/__tests__/blob-ref.test.ts

@@ -0,0 +1,103 @@
+import { describe, test, expect } from 'bun:test';
+
+import { createBlobRef, isBlobRef } from '../blob-ref';
+
+describe('BlobRef', () => {
+  const sampleData = new Uint8Array([137, 80, 78, 71]);
+
+  describe('createBlobRef', () => {
+    test('returns a frozen object with the provided fields', () => {
+      const ref = createBlobRef({
+        data: sampleData,
+        mimeType: 'image/png',
+        name: 'image.png',
+        size: 4,
+      });
+
+      expect(ref.name).toBe('image.png');
+      expect(ref.mimeType).toBe('image/png');
+      expect(ref.size).toBe(4);
+      expect(ref.data).toBe(sampleData);
+      expect(Object.isFrozen(ref)).toBe(true);
+    });
+
+    test('works with ReadableStream data', () => {
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(sampleData);
+          controller.close();
+        },
+      });
+
+      const ref = createBlobRef({
+        data: stream,
+        mimeType: 'video/mp4',
+        name: 'video.mp4',
+        size: 1024,
+      });
+
+      expect(ref.data).toBeInstanceOf(ReadableStream);
+    });
+  });
+
+  describe('isBlobRef', () => {
+    test('returns true for a valid BlobRef with Uint8Array data', () => {
+      const ref = createBlobRef({
+        data: sampleData,
+        mimeType: 'application/octet-stream',
+        name: 'file.bin',
+        size: 4,
+      });
+
+      expect(isBlobRef(ref)).toBe(true);
+    });
+
+    test('returns true for a valid BlobRef with ReadableStream data', () => {
+      const stream = new ReadableStream<Uint8Array>();
+      const ref = createBlobRef({
+        data: stream,
+        mimeType: 'application/octet-stream',
+        name: 'file.bin',
+        size: 0,
+      });
+
+      expect(isBlobRef(ref)).toBe(true);
+    });
+
+    test('returns true for a plain object matching the shape', () => {
+      expect(
+        isBlobRef({
+          data: new Uint8Array(),
+          mimeType: 'application/pdf',
+          name: 'doc.pdf',
+          size: 999,
+        })
+      ).toBe(true);
+    });
+
+    test('returns false for null', () => {
+      expect(isBlobRef(null)).toBe(false);
+    });
+
+    test('returns false for a string', () => {
+      expect(isBlobRef('not a blob')).toBe(false);
+    });
+
+    test('returns false when name is missing', () => {
+      expect(
+        isBlobRef({ data: new Uint8Array(), mimeType: 'text/plain', size: 0 })
+      ).toBe(false);
+    });
+
+    test('returns false when data is a plain object', () => {
+      expect(
+        isBlobRef({
+          data: {},
+          mimeType: 'text/plain',
+          name: 'x',
+          size: 0,
+        })
+      ).toBe(false);
+    });
+  });
+});

package/src/__tests__/branded.test.ts

@@ -0,0 +1,148 @@
+import { describe, test, expect } from 'bun:test';
+
+import {
+  brand,
+  unbrand,
+  uuid,
+  email,
+  nonEmptyString,
+  positiveInt,
+  shortId,
+  hashId,
+} from '../branded';
+
+describe('branded', () => {
+  describe('brand / unbrand', () => {
+    test('brand wraps and unbrand unwraps', () => {
+      const branded = brand('Tag', 'hello');
+      expect(unbrand(branded)).toBe('hello');
+    });
+
+    test('branded value is still usable as base type at runtime', () => {
+      const branded = brand('PositiveInt', 42);
+      expect(branded + 1).toBe(43);
+    });
+  });
+
+  describe('uuid()', () => {
+    test('accepts a valid v4 UUID', () => {
+      const result = uuid('550e8400-e29b-41d4-a716-446655440000');
+      expect(result.isOk()).toBe(true);
+      const value: string = unbrand(result.unwrap());
+      expect(value).toBe('550e8400-e29b-41d4-a716-446655440000');
+    });
+
+    test('rejects an empty string', () => {
+      const result = uuid('');
+      expect(result.isErr()).toBe(true);
+    });
+
+    test('rejects a malformed UUID', () => {
+      const result = uuid('not-a-uuid');
+      expect(result.isErr()).toBe(true);
+    });
+
+    test('rejects UUID missing hyphens', () => {
+      const result = uuid('550e8400e29b41d4a716446655440000');
+      expect(result.isErr()).toBe(true);
+    });
+  });
+
+  describe('email()', () => {
+    test('accepts a simple email', () => {
+      const result = email('test@example.com');
+      expect(result.isOk()).toBe(true);
+    });
+
+    test('rejects missing @', () => {
+      const result = email('testexample.com');
+      expect(result.isErr()).toBe(true);
+    });
+
+    test('rejects missing domain', () => {
+      const result = email('test@');
+      expect(result.isErr()).toBe(true);
+    });
+
+    test('rejects empty string', () => {
+      const result = email('');
+      expect(result.isErr()).toBe(true);
+    });
+  });
+
+  describe('nonEmptyString()', () => {
+    test('accepts a non-empty string', () => {
+      const result = nonEmptyString('hello');
+      expect(result.isOk()).toBe(true);
+    });
+
+    test('rejects an empty string', () => {
+      const result = nonEmptyString('');
+      expect(result.isErr()).toBe(true);
+    });
+  });
+
+  describe('positiveInt()', () => {
+    test('accepts 1', () => {
+      const result = positiveInt(1);
+      expect(result.isOk()).toBe(true);
+    });
+
+    test('accepts a large integer', () => {
+      const result = positiveInt(1_000_000);
+      expect(result.isOk()).toBe(true);
+    });
+
+    test('rejects 0', () => {
+      const result = positiveInt(0);
+      expect(result.isErr()).toBe(true);
+    });
+
+    test('rejects negative numbers', () => {
+      const result = positiveInt(-5);
+      expect(result.isErr()).toBe(true);
+    });
+
+    test('rejects non-integers', () => {
+      const result = positiveInt(1.5);
+      expect(result.isErr()).toBe(true);
+    });
+  });
+
+  describe('shortId()', () => {
+    test('returns a string of default length 8', () => {
+      const id = shortId();
+      expect(id).toHaveLength(8);
+    });
+
+    test('respects custom length', () => {
+      const id = shortId(16);
+      expect(id).toHaveLength(16);
+    });
+
+    test('contains only alphanumeric characters', () => {
+      const id = shortId(100);
+      expect(id).toMatch(/^[A-Za-z0-9]+$/);
+    });
+
+    test('produces unique values', () => {
+      const ids = new Set(Array.from({ length: 50 }, () => shortId()));
+      expect(ids.size).toBe(50);
+    });
+  });
+
+  describe('hashId()', () => {
+    test('returns a hex string', () => {
+      const id = hashId('test');
+      expect(id).toMatch(/^[0-9a-f]{8}$/);
+    });
+
+    test('is deterministic', () => {
+      expect(hashId('hello')).toBe(hashId('hello'));
+    });
+
+    test('different inputs produce different outputs', () => {
+      expect(hashId('a')).not.toBe(hashId('b'));
+    });
+  });
+});