@outfitter/types 0.1.0-rc.1

package/README.md

@@ -0,0 +1,13 @@
+# @outfitter/types
+
+Branded types, type guards, and type utilities for Outfitter.
+
+## Installation
+
+```bash
+bun add @outfitter/types
+```
+
+## Status
+
+This package is in early development. API may change.

package/dist/branded.d.ts

@@ -0,0 +1,129 @@
+import { ValidationError } from "@outfitter/contracts";
+import { Result } from "better-result";
+/**
+* Creates a branded type by adding a unique brand to a base type.
+* This enables nominal typing for primitive types.
+*
+* @example
+* ```typescript
+* type UserId = Branded<string, "UserId">;
+* type PostId = Branded<string, "PostId">;
+*
+* // These are now incompatible at compile time
+* const userId: UserId = brand<string, "UserId">("user_123");
+* const postId: PostId = brand<string, "PostId">("post_456");
+* ```
+*/
+type Branded<
+	T,
+	Brand extends string
+> = T & {
+	readonly __brand: Brand;
+};
+/**
+* Brands a value with a nominal type marker.
+*
+* @param value - The value to brand
+* @returns The branded value
+* @throws Error - Not implemented yet
+*/
+declare function brand<
+	T,
+	Brand extends string
+>(value: T): Branded<T, Brand>;
+/**
+* Removes the brand from a branded type, returning the underlying type.
+*
+* @param value - The branded value
+* @returns The unbranded value
+* @throws Error - Not implemented yet
+*/
+declare function unbrand<
+	T,
+	Brand extends string
+>(value: Branded<T, Brand>): T;
+/**
+* Type helper to extract the underlying type from a branded type.
+*/
+type Unbrand<T> = T extends Branded<infer U, string> ? U : T;
+/**
+* Type helper to extract the brand string from a branded type.
+*/
+type BrandOf<T> = T extends Branded<unknown, infer B> ? B : never;
+/**
+* A positive integer (value > 0, must be a finite integer).
+*/
+type PositiveInt = Branded<number, "PositiveInt">;
+/**
+* A non-empty string (trimmed length > 0).
+*/
+type NonEmptyString = Branded<string, "NonEmptyString">;
+/**
+* An email address (basic format validation: contains @ and . in domain).
+*/
+type Email = Branded<string, "Email">;
+/**
+* A UUID string (UUID v4 format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
+*/
+type UUID = Branded<string, "UUID">;
+/**
+* Creates a PositiveInt from a number, validating that it is a positive integer.
+*
+* @param value - The number to validate
+* @returns Result containing PositiveInt on success, ValidationError on failure
+*
+* @example
+* ```typescript
+* const result = positiveInt(42);
+* if (Result.isOk(result)) {
+*   console.log(result.value); // 42 as PositiveInt
+* }
+* ```
+*/
+declare function positiveInt(value: number): Result<PositiveInt, InstanceType<typeof ValidationError>>;
+/**
+* Creates a NonEmptyString from a string, validating that it has content after trimming.
+*
+* @param value - The string to validate
+* @returns Result containing NonEmptyString on success, ValidationError on failure
+*
+* @example
+* ```typescript
+* const result = nonEmptyString("hello");
+* if (Result.isOk(result)) {
+*   console.log(result.value); // "hello" as NonEmptyString
+* }
+* ```
+*/
+declare function nonEmptyString(value: string): Result<NonEmptyString, InstanceType<typeof ValidationError>>;
+/**
+* Creates an Email from a string, validating basic email format.
+*
+* @param value - The string to validate
+* @returns Result containing Email on success, ValidationError on failure
+*
+* @example
+* ```typescript
+* const result = email("user@example.com");
+* if (Result.isOk(result)) {
+*   console.log(result.value); // "user@example.com" as Email
+* }
+* ```
+*/
+declare function email(value: string): Result<Email, InstanceType<typeof ValidationError>>;
+/**
+* Creates a UUID from a string, validating UUID v4 format.
+*
+* @param value - The string to validate
+* @returns Result containing UUID on success, ValidationError on failure
+*
+* @example
+* ```typescript
+* const result = uuid("550e8400-e29b-41d4-a716-446655440000");
+* if (Result.isOk(result)) {
+*   console.log(result.value); // UUID branded string
+* }
+* ```
+*/
+declare function uuid(value: string): Result<UUID, InstanceType<typeof ValidationError>>;
+export { uuid, unbrand, positiveInt, nonEmptyString, email, brand, Unbrand, UUID, PositiveInt, NonEmptyString, Email, Branded, BrandOf };

package/dist/branded.js

@@ -0,0 +1,68 @@
+// @bun
+// packages/types/src/branded.ts
+import { ValidationError } from "@outfitter/contracts";
+import { Result } from "better-result";
+function brand(value) {
+  return value;
+}
+function unbrand(value) {
+  return value;
+}
+function positiveInt(value) {
+  if (!Number.isFinite(value)) {
+    return Result.err(new ValidationError({
+      message: "Value must be a finite number",
+      field: "value"
+    }));
+  }
+  if (!Number.isInteger(value)) {
+    return Result.err(new ValidationError({
+      message: "Value must be an integer",
+      field: "value"
+    }));
+  }
+  if (value <= 0) {
+    return Result.err(new ValidationError({
+      message: "Value must be greater than 0",
+      field: "value"
+    }));
+  }
+  return Result.ok(brand(value));
+}
+function nonEmptyString(value) {
+  if (value.trim().length === 0) {
+    return Result.err(new ValidationError({
+      message: "String must not be empty or whitespace-only",
+      field: "value"
+    }));
+  }
+  return Result.ok(brand(value));
+}
+var EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function email(value) {
+  if (!EMAIL_REGEX.test(value)) {
+    return Result.err(new ValidationError({
+      message: "Invalid email format",
+      field: "value"
+    }));
+  }
+  return Result.ok(brand(value));
+}
+var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function uuid(value) {
+  if (!UUID_REGEX.test(value)) {
+    return Result.err(new ValidationError({
+      message: "Invalid UUID v4 format",
+      field: "value"
+    }));
+  }
+  return Result.ok(brand(value));
+}
+export {
+  uuid,
+  unbrand,
+  positiveInt,
+  nonEmptyString,
+  email,
+  brand
+};

package/dist/collections.d.ts

@@ -0,0 +1,67 @@
+/**
+* Collection type utilities.
+*
+* @module collections
+*/
+/**
+* A non-empty array type that guarantees at least one element.
+*/
+type NonEmptyArray<T> = [T, ...T[]];
+/**
+* Type guard for checking if an array is non-empty.
+*
+* @param array - The array to check
+* @returns True if the array has at least one element
+*
+* @example
+* ```typescript
+* const items: string[] = getItems();
+* if (isNonEmptyArray(items)) {
+*   const first = items[0]; // Type is string, not string | undefined
+* }
+* ```
+*/
+declare function isNonEmptyArray<T>(array: T[]): array is NonEmptyArray<T>;
+/**
+* Creates a non-empty array, throwing if the input is empty.
+*
+* @param array - The array to convert
+* @returns A non-empty array
+* @throws Error - If the array is empty
+* @throws Error - Not implemented yet
+*/
+declare function toNonEmptyArray<T>(array: T[]): NonEmptyArray<T>;
+/**
+* Gets the first element of a non-empty array.
+*
+* @param array - A non-empty array
+* @returns The first element (guaranteed to exist)
+*/
+declare function first<T>(array: NonEmptyArray<T>): T;
+/**
+* Gets the last element of a non-empty array.
+*
+* @param array - A non-empty array
+* @returns The last element (guaranteed to exist)
+*/
+declare function last<T>(array: NonEmptyArray<T>): T;
+/**
+* Groups array elements by a key function.
+*
+* @param items - The items to group
+* @param keyFn - Function to extract the grouping key
+* @returns A map of keys to arrays of items
+* @throws Error - Not implemented yet
+*
+* @example
+* ```typescript
+* const users = [{ name: "Alice", role: "admin" }, { name: "Bob", role: "user" }];
+* const byRole = groupBy(users, (u) => u.role);
+* // Map { "admin" => [{ name: "Alice", ... }], "user" => [{ name: "Bob", ... }] }
+* ```
+*/
+declare function groupBy<
+	T,
+	K extends string | number | symbol
+>(items: T[], keyFn: (item: T) => K): Map<K, NonEmptyArray<T>>;
+export { toNonEmptyArray, last, isNonEmptyArray, groupBy, first, NonEmptyArray };

package/dist/collections.js

@@ -0,0 +1,37 @@
+// @bun
+// packages/types/src/collections.ts
+function isNonEmptyArray(array) {
+  return array.length > 0;
+}
+function toNonEmptyArray(array) {
+  if (array.length === 0) {
+    throw new Error("Array is empty");
+  }
+  return array;
+}
+function first(array) {
+  return array[0];
+}
+function last(array) {
+  return array.at(-1);
+}
+function groupBy(items, keyFn) {
+  const result = new Map;
+  for (const item of items) {
+    const key = keyFn(item);
+    const existing = result.get(key);
+    if (existing) {
+      existing.push(item);
+    } else {
+      result.set(key, [item]);
+    }
+  }
+  return result;
+}
+export {
+  toNonEmptyArray,
+  last,
+  isNonEmptyArray,
+  groupBy,
+  first
+};

package/dist/deep.d.ts

@@ -0,0 +1,99 @@
+/**
+* Deep path type utilities for type-safe dot-notation access.
+*
+* These utilities enable type-safe access to nested object properties using
+* dot-notation string paths, commonly used in configuration systems and
+* state management.
+*
+* @module deep
+*/
+/**
+* Recursively extracts all valid dot-notation paths from an object type.
+*
+* This type generates a union of all possible paths through an object,
+* including intermediate object paths and final leaf paths.
+*
+* Arrays are treated as leaf nodes - the type does not recurse into array
+* indices (e.g., "items.0" is not generated for `{ items: string[] }`).
+*
+* @typeParam T - The object type to extract paths from
+*
+* @example
+* ```ts
+* type Config = { database: { host: string; port: number }; debug: boolean };
+* type Keys = DeepKeys<Config>;
+* // "database" | "database.host" | "database.port" | "debug"
+* ```
+*
+* @example
+* ```ts
+* // Arrays are leaf nodes
+* type WithArray = { items: string[]; nested: { list: number[] } };
+* type Keys = DeepKeys<WithArray>;
+* // "items" | "nested" | "nested.list"
+* ```
+*/
+type DeepKeys<T> = T extends object ? T extends readonly unknown[] ? never : { [K in keyof T & string] : NonNullable<T[K]> extends object ? NonNullable<T[K]> extends readonly unknown[] ? K : K | `${K}.${DeepKeys<NonNullable<T[K]>>}` : K }[keyof T & string] : never;
+/**
+* Gets the type at a specific dot-notation path.
+*
+* Given an object type and a path string, this type resolves to the
+* type of the value at that path. Returns `never` for invalid paths.
+*
+* @typeParam T - The object type to access
+* @typeParam P - The dot-notation path string
+*
+* @example
+* ```ts
+* type Config = { database: { host: string; port: number } };
+* type Host = DeepGet<Config, "database.host">; // string
+* type Port = DeepGet<Config, "database.port">; // number
+* type DB = DeepGet<Config, "database">;        // { host: string; port: number }
+* ```
+*
+* @example
+* ```ts
+* type Config = { database: { host: string } };
+* type Invalid = DeepGet<Config, "database.invalid">; // never
+* ```
+*/
+type DeepGet<
+	T,
+	P extends string
+> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? DeepGet<T[K], Rest> : never : P extends keyof T ? T[P] : never;
+/**
+* Creates a new type with the value at path P replaced with V.
+*
+* This type is useful for typing immutable update functions that modify
+* values at specific paths while preserving the rest of the object structure.
+*
+* Returns `never` if the path is invalid.
+*
+* @typeParam T - The original object type
+* @typeParam P - The dot-notation path to the value to replace
+* @typeParam V - The new type for the value at the path
+*
+* @example
+* ```ts
+* type Config = { database: { host: string; port: number } };
+*
+* // Replace port type from number to string
+* type Updated = DeepSet<Config, "database.port", string>;
+* // { database: { host: string; port: string } }
+* ```
+*
+* @example
+* ```ts
+* type State = { user: { name: string; age: number } };
+*
+* // Replace entire nested object
+* type Updated = DeepSet<State, "user", { id: number }>;
+* // { user: { id: number } }
+* ```
+*/
+type DeepSet<
+	T,
+	P extends string,
+	V
+> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? { [Key in keyof T] : Key extends K ? DeepSet<T[Key], Rest, V> : T[Key] } : never : P extends keyof T ? { [Key in keyof T] : Key extends P ? V : T[Key] } : never;
+export { DeepSet, DeepKeys, DeepGet };

package/dist/deep.js

@@ -0,0 +1 @@
+// @bun

package/dist/guards.d.ts

@@ -0,0 +1,67 @@
+/**
+* Type guard utilities for runtime type checking.
+*
+* @module guards
+*/
+/**
+* Type guard for checking if a value is defined (not null or undefined).
+*
+* @param value - The value to check
+* @returns True if the value is not null or undefined
+*
+* @example
+* ```typescript
+* const items = [1, null, 2, undefined, 3];
+* const defined = items.filter(isDefined); // [1, 2, 3]
+* ```
+*/
+declare function isDefined<T>(value: T | null | undefined): value is T;
+/**
+* Type guard for checking if a value is a non-empty string.
+*
+* @param value - The value to check
+* @returns True if the value is a string with length > 0
+*/
+declare function isNonEmptyString(value: unknown): value is string;
+/**
+* Type guard for checking if a value is a plain object.
+*
+* @param value - The value to check
+* @returns True if the value is a plain object (not null, array, or other object types)
+*/
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+* Type guard for checking if a value has a specific property.
+*
+* @param value - The value to check
+* @param key - The property key to look for
+* @returns True if the value is an object with the specified property
+*/
+declare function hasProperty<K extends string>(value: unknown, key: K): value is Record<K, unknown>;
+/**
+* Creates a type guard function for a specific type using a predicate.
+*
+* @param predicate - A function that returns true if the value matches the type
+* @returns A type guard function
+* @throws Error - Not implemented yet
+*
+* @example
+* ```typescript
+* interface User { name: string; age: number; }
+* const isUser = createGuard<User>(
+*   (v) => hasProperty(v, "name") && hasProperty(v, "age")
+* );
+* ```
+*/
+declare function createGuard<T>(predicate: (value: unknown) => boolean): (value: unknown) => value is T;
+/**
+* Asserts that a value matches a type guard, throwing if it doesn't.
+*
+* @param value - The value to assert
+* @param guard - The type guard to use
+* @param message - Optional error message
+* @throws Error - If the value doesn't match the guard
+* @throws Error - Not implemented yet
+*/
+declare function assertType<T>(value: unknown, guard: (value: unknown) => value is T, message?: string): asserts value is T;
+export { isPlainObject, isNonEmptyString, isDefined, hasProperty, createGuard, assertType };

package/dist/guards.js

@@ -0,0 +1,30 @@
+// @bun
+// packages/types/src/guards.ts
+function isDefined(value) {
+  return value !== null && value !== undefined;
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+}
+function hasProperty(value, key) {
+  return isPlainObject(value) && key in value;
+}
+function createGuard(predicate) {
+  return (value) => predicate(value);
+}
+function assertType(value, guard, message) {
+  if (!guard(value)) {
+    throw new Error(message ?? "Type assertion failed");
+  }
+}
+export {
+  isPlainObject,
+  isNonEmptyString,
+  isDefined,
+  hasProperty,
+  createGuard,
+  assertType
+};

package/dist/hash-id.d.ts

@@ -0,0 +1,17 @@
+/**
+* Generates a deterministic short ID from input using Bun.hash().
+* Unlike shortId() which generates random IDs, hashId() always produces
+* the same output for the same input.
+*
+* @param input - String to hash
+* @param length - Output length (default: 5)
+* @returns URL-safe alphanumeric hash (base62)
+*
+* @example
+* ```typescript
+* hashId("user-123")        // "a7b2c" (always same for same input)
+* hashId("user-123", 8)     // "a7b2c3d1"
+* ```
+*/
+declare function hashId(input: string, length?: number): string;
+export { hashId };

package/dist/hash-id.js

@@ -0,0 +1,25 @@
+// @bun
+// packages/types/src/hash-id.ts
+var BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+function toBase62(num) {
+  if (num === 0n)
+    return "0";
+  const base = BigInt(BASE62.length);
+  let result = "";
+  let value = num;
+  while (value > 0n) {
+    const remainder = Number(value % base);
+    result = BASE62[remainder] + result;
+    value /= base;
+  }
+  return result;
+}
+function hashId(input, length = 5) {
+  const hash = Bun.hash(input);
+  const base62 = toBase62(BigInt(hash));
+  const padded = base62.padStart(length, "0");
+  return padded.slice(0, length);
+}
+export {
+  hashId
+};