@outfitter/types 0.1.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,499 @@
+/**
+* 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;
+/**
+* General type utilities for TypeScript.
+*
+* @module utilities
+*/
+/**
+* Makes specific properties of a type required.
+*
+* @example
+* ```typescript
+* interface Config { host?: string; port?: number; }
+* type RequiredHost = RequiredKeys<Config, "host">;
+* // { host: string; port?: number; }
+* ```
+*/
+type RequiredKeys<
+	T,
+	K extends keyof T
+> = T & Required<Pick<T, K>>;
+/**
+* Makes specific properties of a type optional.
+*
+* @example
+* ```typescript
+* interface User { id: string; name: string; email: string; }
+* type PartialUser = OptionalKeys<User, "email">;
+* // { id: string; name: string; email?: string; }
+* ```
+*/
+type OptionalKeys<
+	T,
+	K extends keyof T
+> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+* Deeply makes all properties readonly.
+*/
+type DeepReadonly<T> = { readonly [P in keyof T] : T[P] extends object ? DeepReadonly<T[P]> : T[P] };
+/**
+* Deeply makes all properties partial (optional).
+*/
+type DeepPartial<T> = { [P in keyof T]? : T[P] extends object ? DeepPartial<T[P]> : T[P] };
+/**
+* Creates a type that requires at least one of the specified keys.
+*
+* @example
+* ```typescript
+* type Props = AtLeastOne<{ a?: string; b?: number; c?: boolean }, "a" | "b">;
+* // Must have at least 'a' or 'b'
+* ```
+*/
+type AtLeastOne<
+	T,
+	Keys extends keyof T = keyof T
+> = Omit<T, Keys> & { [K in Keys]-? : Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>> }[Keys];
+/**
+* Creates a type that requires exactly one of the specified keys.
+*
+* @example
+* ```typescript
+* type Auth = ExactlyOne<{ token?: string; apiKey?: string }, "token" | "apiKey">;
+* // Must have exactly one of 'token' or 'apiKey', not both
+* ```
+*/
+type ExactlyOne<
+	T,
+	Keys extends keyof T = keyof T
+> = Omit<T, Keys> & { [K in Keys]-? : Required<Pick<T, K>> & Partial<Record<Exclude<Keys, K>, never>> }[Keys];
+/**
+* Extracts the element type from an array type.
+*/
+type ElementOf<T> = T extends readonly (infer E)[] ? E : never;
+/**
+* Creates a union type from object values.
+*/
+type ValueOf<T> = T[keyof T];
+/**
+* Makes a type's properties mutable (removes readonly).
+*/
+type Mutable<T> = { -readonly [P in keyof T] : T[P] };
+/**
+* Asserts at compile time that a type is never (exhaustiveness check).
+*
+* @param value - The value that should be never
+* @throws Error - Always throws if reached at runtime
+*
+* @example
+* ```typescript
+* type Status = "pending" | "done";
+* function handle(status: Status) {
+*   switch (status) {
+*     case "pending": return "...";
+*     case "done": return "ok";
+*     default: return assertNever(status);
+*   }
+* }
+* ```
+*/
+declare function assertNever(value: never): never;
+/**
+* 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>>;
+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>>;
+/**
+* A short identifier string, typically 7-12 characters.
+* Used for human-readable references (e.g., commit SHAs, session IDs).
+*/
+type ShortId = Branded<string, "ShortId">;
+/**
+* Options for short ID generation.
+*/
+interface ShortIdOptions {
+	/** Length of the generated ID. Default: 8 */
+	length?: number;
+	/** Character set to use. Default: alphanumeric */
+	charset?: "alphanumeric" | "hex" | "base62";
+	/** Optional prefix to prepend */
+	prefix?: string;
+}
+declare function shortId(options?: ShortIdOptions): ShortId;
+/**
+* Validates that a string matches the short ID format.
+*
+* @param value - The string to validate
+* @param options - Validation options (must match generation options)
+* @returns True if the string is a valid short ID
+* @throws Error - Not implemented yet
+*/
+declare function isShortId(value: string, options?: ShortIdOptions): value is ShortId;
+/**
+* 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;
+/**
+* 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 { uuid, unbrand, toNonEmptyArray, shortId, positiveInt, nonEmptyString, last, isShortId, isPlainObject, isNonEmptyString, isNonEmptyArray, isDefined, hashId, hasProperty, groupBy, first, email, createGuard, brand, assertType, assertNever, ValueOf, Unbrand, UUID, ShortIdOptions, ShortId, RequiredKeys, PositiveInt, OptionalKeys, NonEmptyString, NonEmptyArray, Mutable, ExactlyOne, Email, ElementOf, DeepSet, DeepReadonly, DeepPartial, DeepKeys, DeepGet, Branded, BrandOf, AtLeastOne };

package/dist/index.js

@@ -0,0 +1,57 @@
+// @bun
+import {
+  assertNever
+} from "./utilities.js";
+import {
+  first,
+  groupBy,
+  isNonEmptyArray,
+  last,
+  toNonEmptyArray
+} from "./collections.js";
+import {
+  isShortId,
+  shortId
+} from "./short-id.js";
+import {
+  hashId
+} from "./hash-id.js";
+import {
+  brand,
+  email,
+  nonEmptyString,
+  positiveInt,
+  unbrand,
+  uuid
+} from "./branded.js";
+import {
+  assertType,
+  createGuard,
+  hasProperty,
+  isDefined,
+  isNonEmptyString,
+  isPlainObject
+} from "./guards.js";
+export {
+  uuid,
+  unbrand,
+  toNonEmptyArray,
+  shortId,
+  positiveInt,
+  nonEmptyString,
+  last,
+  isShortId,
+  isPlainObject,
+  isNonEmptyString,
+  isNonEmptyArray,
+  isDefined,
+  hashId,
+  hasProperty,
+  groupBy,
+  first,
+  email,
+  createGuard,
+  brand,
+  assertType,
+  assertNever
+};

package/dist/short-id.d.ts

@@ -0,0 +1,47 @@
+/**
+* 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;
+};
+/**
+* A short identifier string, typically 7-12 characters.
+* Used for human-readable references (e.g., commit SHAs, session IDs).
+*/
+type ShortId = Branded<string, "ShortId">;
+/**
+* Options for short ID generation.
+*/
+interface ShortIdOptions {
+	/** Length of the generated ID. Default: 8 */
+	length?: number;
+	/** Character set to use. Default: alphanumeric */
+	charset?: "alphanumeric" | "hex" | "base62";
+	/** Optional prefix to prepend */
+	prefix?: string;
+}
+declare function shortId(options?: ShortIdOptions): ShortId;
+/**
+* Validates that a string matches the short ID format.
+*
+* @param value - The string to validate
+* @param options - Validation options (must match generation options)
+* @returns True if the string is a valid short ID
+* @throws Error - Not implemented yet
+*/
+declare function isShortId(value: string, options?: ShortIdOptions): value is ShortId;
+export { shortId, isShortId, ShortIdOptions, ShortId };

package/dist/short-id.js

@@ -0,0 +1,41 @@
+// @bun
+// packages/types/src/short-id.ts
+var CHARSETS = {
+  alphanumeric: "0123456789abcdefghijklmnopqrstuvwxyz",
+  hex: "0123456789abcdef",
+  base62: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+};
+function shortId(options) {
+  const length = options?.length ?? 8;
+  const charset = CHARSETS[options?.charset ?? "alphanumeric"];
+  const prefix = options?.prefix ?? "";
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  let result = "";
+  for (const byte of bytes) {
+    result += charset[byte % charset.length];
+  }
+  return prefix + result;
+}
+function isShortId(value, options) {
+  const length = options?.length ?? 8;
+  const charset = CHARSETS[options?.charset ?? "alphanumeric"];
+  const prefix = options?.prefix ?? "";
+  if (prefix && !value.startsWith(prefix)) {
+    return false;
+  }
+  const idPart = prefix ? value.slice(prefix.length) : value;
+  if (idPart.length !== length) {
+    return false;
+  }
+  for (const char of idPart) {
+    if (!charset.includes(char)) {
+      return false;
+    }
+  }
+  return true;
+}
+export {
+  shortId,
+  isShortId
+};