@dotdo/postgres 0.1.0

package/src/types/utilities.ts

@@ -0,0 +1,1023 @@
+/**
+ * Type Utilities for postgres.do
+ *
+ * Reusable type patterns and utilities for improved type safety and inference.
+ * This module provides foundational type utilities used throughout the codebase.
+ *
+ * ## Type Categories
+ *
+ * 1. **Nullable Types** - Safe handling of null/undefined
+ * 2. **Constructor Types** - Class instantiation patterns
+ * 3. **Result Types** - Success/failure discriminated unions
+ * 4. **Deep Types** - Recursive type transformations
+ * 5. **Async Types** - Promise and awaitable patterns
+ * 6. **Record Utilities** - Object manipulation types
+ * 7. **Function Utilities** - Function signature types
+ *
+ * @module types/utilities
+ */
+
+// =============================================================================
+// Nullable Types
+// =============================================================================
+
+/**
+ * Makes a type nullable (T | null).
+ *
+ * @typeParam T - The base type to make nullable
+ *
+ * @example
+ * ```typescript
+ * type MaybeUser = Nullable<User>
+ * // Equivalent to: User | null
+ *
+ * function findUser(id: string): Nullable<User> {
+ *   return users.get(id) ?? null
+ * }
+ * ```
+ */
+export type Nullable<T> = T | null
+
+/**
+ * Makes a type optional (T | undefined).
+ *
+ * @typeParam T - The base type to make optional
+ *
+ * @example
+ * ```typescript
+ * type MaybeConfig = Optional<Config>
+ * // Equivalent to: Config | undefined
+ * ```
+ */
+export type Optional<T> = T | undefined
+
+/**
+ * Makes a type nullable and optional (T | null | undefined).
+ * Also known as "Maybe" in some type systems.
+ *
+ * @typeParam T - The base type
+ *
+ * @example
+ * ```typescript
+ * type MaybeValue = Maybe<string>
+ * // Equivalent to: string | null | undefined
+ * ```
+ */
+export type Maybe<T> = T | null | undefined
+
+/**
+ * Excludes null and undefined from a type.
+ * Useful for asserting non-nullable values.
+ *
+ * @typeParam T - The type to make non-nullable
+ *
+ * @example
+ * ```typescript
+ * type Value = Maybe<string>
+ * type DefiniteValue = NonNullish<Value>
+ * // Result: string
+ * ```
+ */
+export type NonNullish<T> = Exclude<T, null | undefined>
+
+// =============================================================================
+// Constructor Types
+// =============================================================================
+
+/**
+ * Represents a constructor function that creates instances of type T.
+ *
+ * @typeParam T - The type of instances created (defaults to object)
+ *
+ * @example
+ * ```typescript
+ * // Mixin pattern
+ * function withLogging<T extends Constructor>(Base: T) {
+ *   return class extends Base {
+ *     log(message: string) {
+ *       console.log(message)
+ *     }
+ *   }
+ * }
+ *
+ * const LoggingUser = withLogging(User)
+ * const user = new LoggingUser()
+ * user.log('Hello')
+ * ```
+ */
+export type Constructor<T = object> = new (...args: unknown[]) => T
+
+/**
+ * Constructor with specific argument types.
+ *
+ * @typeParam T - The type of instances created
+ * @typeParam Args - Tuple of constructor argument types
+ *
+ * @example
+ * ```typescript
+ * type UserConstructor = ConstructorWithArgs<User, [string, number]>
+ * // Represents: new (name: string, age: number) => User
+ * ```
+ */
+export type ConstructorWithArgs<T, Args extends unknown[]> = new (...args: Args) => T
+
+/**
+ * Abstract constructor for abstract class patterns.
+ *
+ * @typeParam T - The type of instances created
+ *
+ * @example
+ * ```typescript
+ * abstract class BaseService {
+ *   abstract process(): void
+ * }
+ *
+ * function createService<T extends AbstractConstructor<BaseService>>(
+ *   ServiceClass: T
+ * ): InstanceType<T> {
+ *   // ...
+ * }
+ * ```
+ */
+export type AbstractConstructor<T = object> = abstract new (...args: unknown[]) => T
+
+// =============================================================================
+// Result Types (Discriminated Unions)
+// =============================================================================
+
+/**
+ * Represents a successful result with a value.
+ *
+ * @typeParam T - The type of the success value
+ */
+export interface Success<T> {
+  readonly success: true
+  readonly value: T
+  readonly error?: never
+}
+
+/**
+ * Represents a failed result with an error.
+ *
+ * @typeParam E - The type of the error (defaults to Error)
+ */
+export interface Failure<E = Error> {
+  readonly success: false
+  readonly value?: never
+  readonly error: E
+}
+
+/**
+ * Result type for operations that can succeed or fail.
+ * Use this for explicit error handling without exceptions.
+ *
+ * @typeParam T - The success value type
+ * @typeParam E - The error type (defaults to Error)
+ *
+ * @example
+ * ```typescript
+ * function parseJson<T>(json: string): Result<T, SyntaxError> {
+ *   try {
+ *     return { success: true, value: JSON.parse(json) }
+ *   } catch (e) {
+ *     return { success: false, error: e as SyntaxError }
+ *   }
+ * }
+ *
+ * const result = parseJson<User>('{"name":"John"}')
+ * if (result.success) {
+ *   console.log(result.value.name) // TypeScript knows value exists
+ * } else {
+ *   console.error(result.error.message) // TypeScript knows error exists
+ * }
+ * ```
+ */
+export type Result<T, E = Error> = Success<T> | Failure<E>
+
+/**
+ * Async result for operations that return promises.
+ *
+ * @typeParam T - The success value type
+ * @typeParam E - The error type
+ */
+export type AsyncResult<T, E = Error> = Promise<Result<T, E>>
+
+/**
+ * Creates a success result.
+ *
+ * @param value - The success value
+ * @returns A Success result
+ */
+export function success<T>(value: T): Success<T> {
+  return { success: true, value }
+}
+
+/**
+ * Creates a failure result.
+ *
+ * @param error - The error
+ * @returns A Failure result
+ */
+export function failure<E = Error>(error: E): Failure<E> {
+  return { success: false, error }
+}
+
+/**
+ * Type guard to check if a Result is a Success.
+ *
+ * @param result - The result to check
+ * @returns true if the result is a Success
+ */
+export function isSuccess<T, E>(result: Result<T, E>): result is Success<T> {
+  return result.success === true
+}
+
+/**
+ * Type guard to check if a Result is a Failure.
+ *
+ * @param result - The result to check
+ * @returns true if the result is a Failure
+ */
+export function isFailure<T, E>(result: Result<T, E>): result is Failure<E> {
+  return result.success === false
+}
+
+// =============================================================================
+// Deep Types
+// =============================================================================
+
+/**
+ * Recursively makes all properties of T optional.
+ *
+ * @typeParam T - The type to make deeply partial
+ *
+ * @example
+ * ```typescript
+ * interface Config {
+ *   database: {
+ *     host: string
+ *     port: number
+ *   }
+ * }
+ *
+ * type PartialConfig = DeepPartial<Config>
+ * // All nested properties are optional:
+ * // { database?: { host?: string; port?: number } }
+ * ```
+ */
+export type DeepPartial<T> = T extends object
+  ? { [P in keyof T]?: DeepPartial<T[P]> }
+  : T
+
+/**
+ * Recursively makes all properties of T required.
+ *
+ * @typeParam T - The type to make deeply required
+ */
+export type DeepRequired<T> = T extends object
+  ? { [P in keyof T]-?: DeepRequired<T[P]> }
+  : T
+
+/**
+ * Recursively makes all properties of T readonly.
+ *
+ * @typeParam T - The type to make deeply readonly
+ *
+ * @example
+ * ```typescript
+ * const config: DeepReadonly<Config> = { ... }
+ * config.database.host = 'new' // Error: Cannot assign to readonly property
+ * ```
+ */
+export type DeepReadonly<T> = T extends object
+  ? { readonly [P in keyof T]: DeepReadonly<T[P]> }
+  : T
+
+/**
+ * Recursively makes all properties of T mutable (removes readonly).
+ *
+ * @typeParam T - The type to make deeply mutable
+ */
+export type DeepMutable<T> = T extends object
+  ? { -readonly [P in keyof T]: DeepMutable<T[P]> }
+  : T
+
+// =============================================================================
+// Async Types
+// =============================================================================
+
+/**
+ * Extracts the resolved type from a Promise.
+ *
+ * @typeParam T - The Promise type
+ *
+ * @example
+ * ```typescript
+ * type Result = Awaited<Promise<string>>
+ * // Result: string
+ * ```
+ */
+export type Awaited<T> = T extends Promise<infer U> ? U : T
+
+/**
+ * Represents a value that might be a Promise.
+ *
+ * @typeParam T - The base type
+ *
+ * @example
+ * ```typescript
+ * function process(value: MaybePromise<string>): Promise<string> {
+ *   return Promise.resolve(value)
+ * }
+ *
+ * process('sync')           // Works
+ * process(Promise.resolve('async'))  // Also works
+ * ```
+ */
+export type MaybePromise<T> = T | Promise<T>
+
+/**
+ * Alias for MaybePromise - common in async APIs.
+ */
+export type Awaitable<T> = MaybePromise<T>
+
+/**
+ * Makes a function return type async (wrapped in Promise).
+ *
+ * @typeParam F - The function type
+ */
+export type AsyncFunction<F extends (...args: unknown[]) => unknown> = (
+  ...args: Parameters<F>
+) => Promise<ReturnType<F>>
+
+// =============================================================================
+// Record Utilities
+// =============================================================================
+
+/**
+ * A record with string keys and values of type T.
+ *
+ * @typeParam T - The value type
+ *
+ * @example
+ * ```typescript
+ * type Headers = StringRecord<string>
+ * // Equivalent to: Record<string, string>
+ * ```
+ */
+export type StringRecord<T> = Record<string, T>
+
+/**
+ * Extract keys of T that have values of type V.
+ *
+ * @typeParam T - The object type
+ * @typeParam V - The value type to match
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: number
+ *   name: string
+ *   email: string
+ * }
+ *
+ * type StringKeys = KeysOfType<User, string>
+ * // Result: 'name' | 'email'
+ * ```
+ */
+export type KeysOfType<T, V> = {
+  [K in keyof T]: T[K] extends V ? K : never
+}[keyof T]
+
+/**
+ * Pick properties from T where value extends V.
+ *
+ * @typeParam T - The source object type
+ * @typeParam V - The value type to filter by
+ */
+export type PickByType<T, V> = Pick<T, KeysOfType<T, V>>
+
+/**
+ * Omit properties from T where value extends V.
+ *
+ * @typeParam T - The source object type
+ * @typeParam V - The value type to filter by
+ */
+export type OmitByType<T, V> = Omit<T, KeysOfType<T, V>>
+
+/**
+ * Make specific properties of T required while keeping others unchanged.
+ *
+ * @typeParam T - The base type
+ * @typeParam K - Keys to make required
+ *
+ * @example
+ * ```typescript
+ * interface Config {
+ *   host?: string
+ *   port?: number
+ *   debug?: boolean
+ * }
+ *
+ * type RequiredHostConfig = RequireKeys<Config, 'host'>
+ * // Result: { host: string; port?: number; debug?: boolean }
+ * ```
+ */
+export type RequireKeys<T, K extends keyof T> = T & Required<Pick<T, K>>
+
+/**
+ * Make specific properties of T optional while keeping others unchanged.
+ *
+ * @typeParam T - The base type
+ * @typeParam K - Keys to make optional
+ */
+export type OptionalKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
+
+/**
+ * Get the value type of a Record or object literal.
+ *
+ * @typeParam T - The object type
+ */
+export type ValueOf<T> = T[keyof T]
+
+// =============================================================================
+// Function Utilities
+// =============================================================================
+
+/**
+ * Any function type (use sparingly, prefer specific types).
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyFunction = (...args: any[]) => any
+
+/**
+ * A function that takes no arguments and returns void.
+ */
+export type VoidFunction = () => void
+
+/**
+ * A function that takes no arguments and returns T.
+ */
+export type Thunk<T> = () => T
+
+/**
+ * A predicate function that tests a value.
+ *
+ * @typeParam T - The type being tested
+ */
+export type Predicate<T> = (value: T) => boolean
+
+/**
+ * A type guard predicate function.
+ *
+ * @typeParam T - The input type
+ * @typeParam U - The narrowed type (must extend T)
+ */
+export type TypeGuard<T, U extends T> = (value: T) => value is U
+
+/**
+ * Extract the first parameter type of a function.
+ */
+export type FirstParameter<F extends AnyFunction> = Parameters<F>[0]
+
+/**
+ * Extract the last parameter type of a function.
+ */
+export type LastParameter<F extends AnyFunction> = Parameters<F> extends [...unknown[], infer L]
+  ? L
+  : never
+
+// =============================================================================
+// Utility Type Guards
+// =============================================================================
+
+/**
+ * Type guard to check if a value is not null or undefined.
+ *
+ * @param value - The value to check
+ * @returns true if value is neither null nor undefined
+ *
+ * @example
+ * ```typescript
+ * const values = [1, null, 2, undefined, 3]
+ * const defined = values.filter(isDefined)
+ * // defined: number[] = [1, 2, 3]
+ * ```
+ */
+export function isDefined<T>(value: T | null | undefined): value is T {
+  return value !== null && value !== undefined
+}
+
+/**
+ * Type guard to check if a value is a string.
+ *
+ * @param value - The value to check
+ * @returns true if value is a string
+ */
+export function isString(value: unknown): value is string {
+  return typeof value === 'string'
+}
+
+/**
+ * Type guard to check if a value is a number (and not NaN).
+ *
+ * @param value - The value to check
+ * @returns true if value is a finite number
+ */
+export function isNumber(value: unknown): value is number {
+  return typeof value === 'number' && !Number.isNaN(value)
+}
+
+/**
+ * Type guard to check if a value is a boolean.
+ *
+ * @param value - The value to check
+ * @returns true if value is a boolean
+ */
+export function isBoolean(value: unknown): value is boolean {
+  return typeof value === 'boolean'
+}
+
+/**
+ * Type guard to check if a value is a plain object.
+ *
+ * @param value - The value to check
+ * @returns true if value is a plain object (not null, array, or other types)
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Type guard to check if a value is an array.
+ *
+ * @param value - The value to check
+ * @returns true if value is an array
+ */
+export function isArray<T = unknown>(value: unknown): value is T[] {
+  return Array.isArray(value)
+}
+
+/**
+ * Type guard to check if a value is a function.
+ *
+ * @param value - The value to check
+ * @returns true if value is a function
+ */
+export function isFunction(value: unknown): value is AnyFunction {
+  return typeof value === 'function'
+}
+
+/**
+ * Type guard to check if a value is a Promise.
+ *
+ * @param value - The value to check
+ * @returns true if value is a Promise
+ */
+export function isPromise<T = unknown>(value: unknown): value is Promise<T> {
+  return value instanceof Promise || (
+    isPlainObject(value) &&
+    isFunction((value as { then?: unknown }).then)
+  )
+}
+
+/**
+ * Type guard to check if a value is an Error.
+ *
+ * @param value - The value to check
+ * @returns true if value is an Error
+ */
+export function isError(value: unknown): value is Error {
+  return value instanceof Error
+}
+
+// =============================================================================
+// Assertion Utilities
+// =============================================================================
+
+/**
+ * Assert that a value is defined (not null or undefined).
+ * Throws an error if the assertion fails.
+ *
+ * @param value - The value to check
+ * @param message - Optional error message
+ * @throws Error if value is null or undefined
+ *
+ * @example
+ * ```typescript
+ * const user = users.get(id)
+ * assertDefined(user, `User ${id} not found`)
+ * // user is now narrowed to non-nullable type
+ * console.log(user.name)
+ * ```
+ */
+export function assertDefined<T>(
+  value: T | null | undefined,
+  message = 'Expected value to be defined'
+): asserts value is T {
+  if (value === null || value === undefined) {
+    throw new Error(message)
+  }
+}
+
+/**
+ * Assert that a condition is true.
+ * Throws an error if the condition is false.
+ *
+ * @param condition - The condition to check
+ * @param message - Optional error message
+ * @throws Error if condition is false
+ */
+export function assert(
+  condition: boolean,
+  message = 'Assertion failed'
+): asserts condition {
+  if (!condition) {
+    throw new Error(message)
+  }
+}
+
+/**
+ * Marks code that should be unreachable.
+ * Useful in exhaustive switch statements.
+ *
+ * @param value - The value that should never exist
+ * @param message - Optional error message
+ * @throws Error always
+ *
+ * @example
+ * ```typescript
+ * type Status = 'active' | 'inactive'
+ *
+ * function handleStatus(status: Status) {
+ *   switch (status) {
+ *     case 'active':
+ *       return 'Active'
+ *     case 'inactive':
+ *       return 'Inactive'
+ *     default:
+ *       // TypeScript ensures all cases are handled
+ *       return assertNever(status)
+ *   }
+ * }
+ * ```
+ */
+export function assertNever(value: never, message = 'Unexpected value'): never {
+  throw new Error(`${message}: ${JSON.stringify(value)}`)
+}
+
+// =============================================================================
+// String Literal Utilities
+// =============================================================================
+
+/**
+ * Capitalize the first letter of a string type.
+ */
+export type Capitalize<S extends string> = S extends `${infer F}${infer R}`
+  ? `${Uppercase<F>}${R}`
+  : S
+
+/**
+ * Uncapitalize the first letter of a string type.
+ */
+export type Uncapitalize<S extends string> = S extends `${infer F}${infer R}`
+  ? `${Lowercase<F>}${R}`
+  : S
+
+/**
+ * Join string literals with a delimiter.
+ */
+export type Join<T extends string[], D extends string> = T extends []
+  ? ''
+  : T extends [infer F extends string]
+    ? F
+    : T extends [infer F extends string, ...infer R extends string[]]
+      ? `${F}${D}${Join<R, D>}`
+      : never
+
+// =============================================================================
+// Tuple Utilities
+// =============================================================================
+
+/**
+ * Get the first element type of a tuple.
+ */
+export type Head<T extends unknown[]> = T extends [infer H, ...unknown[]] ? H : never
+
+/**
+ * Get all but the first element type of a tuple.
+ */
+export type Tail<T extends unknown[]> = T extends [unknown, ...infer R] ? R : never
+
+/**
+ * Get the last element type of a tuple.
+ */
+export type Last<T extends unknown[]> = T extends [...unknown[], infer L] ? L : never
+
+/**
+ * Get the length of a tuple.
+ */
+export type Length<T extends unknown[]> = T['length']
+
+// =============================================================================
+// Web API Type Helpers
+// =============================================================================
+
+/**
+ * Type-safe conversion of Uint8Array to BodyInit for Response/Request constructors.
+ *
+ * The Fetch API accepts Uint8Array as BodyInit in most environments, but TypeScript
+ * doesn't reflect this in its type definitions. This helper provides a type-safe
+ * conversion without using `as unknown as BodyInit`.
+ *
+ * @param data - The Uint8Array to convert
+ * @returns The data as a type compatible with Response/Request body
+ *
+ * @example
+ * ```typescript
+ * const data = new Uint8Array([1, 2, 3])
+ * const response = new Response(toBodyInit(data))
+ * ```
+ */
+export function toBodyInit(data: Uint8Array): BodyInit {
+  // Uint8Array is a valid BodyInit in all modern environments
+  // The cast is safe because BufferSource (which includes Uint8Array) is part of BodyInit
+  return data as unknown as BodyInit
+}
+
+/**
+ * Type-safe extraction of ArrayBuffer from various typed array sources.
+ *
+ * Handles the common case of needing a clean ArrayBuffer from various input types,
+ * avoiding SharedArrayBuffer issues in Workers.
+ *
+ * @param source - The source to extract ArrayBuffer from
+ * @returns A non-shared ArrayBuffer copy
+ *
+ * @example
+ * ```typescript
+ * const typedArray = new Uint8Array([1, 2, 3])
+ * const buffer = toArrayBuffer(typedArray)
+ * ```
+ */
+export function toArrayBuffer(source: ArrayBufferLike | ArrayBufferView): ArrayBuffer {
+  if (source instanceof ArrayBuffer) {
+    return source
+  }
+
+  // Handle typed arrays and DataView
+  if (ArrayBuffer.isView(source)) {
+    // Check if the underlying buffer is a SharedArrayBuffer
+    if (source.buffer instanceof ArrayBuffer) {
+      // Regular ArrayBuffer - slice it
+      return source.buffer.slice(source.byteOffset, source.byteOffset + source.byteLength)
+    }
+    // SharedArrayBuffer - copy to new ArrayBuffer
+    const copy = new Uint8Array(source.byteLength)
+    copy.set(new Uint8Array(source.buffer, source.byteOffset, source.byteLength))
+    return copy.buffer
+  }
+
+  // Handle SharedArrayBuffer by copying to a new ArrayBuffer
+  const copy = new Uint8Array(source.byteLength)
+  copy.set(new Uint8Array(source))
+  return copy.buffer
+}
+
+/**
+ * Type guard for checking if a value is an ArrayBufferView (typed array or DataView).
+ *
+ * @param value - The value to check
+ * @returns true if value is an ArrayBufferView
+ */
+export function isArrayBufferView(value: unknown): value is ArrayBufferView {
+  return ArrayBuffer.isView(value)
+}
+
+/**
+ * Type guard for checking if a value is a Uint8Array.
+ *
+ * @param value - The value to check
+ * @returns true if value is a Uint8Array
+ */
+export function isUint8Array(value: unknown): value is Uint8Array {
+  return value instanceof Uint8Array
+}
+
+// =============================================================================
+// Storage Type Helpers
+// =============================================================================
+
+/**
+ * Type-safe narrowing for Cloudflare storage types.
+ *
+ * When reading from KV or DO storage with generic types, the returned value
+ * needs to be narrowed. This helper provides runtime validation with proper
+ * type narrowing.
+ *
+ * @typeParam T - The expected type
+ * @param value - The value from storage
+ * @param validator - A type guard function for T
+ * @returns The value as T if valid, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * interface Config { host: string; port: number }
+ * const isConfig = (v: unknown): v is Config =>
+ *   isPlainObject(v) && isString((v as Config).host)
+ *
+ * const config = narrowStorageValue<Config>(await storage.get('config'), isConfig)
+ * ```
+ */
+export function narrowStorageValue<T>(
+  value: unknown,
+  validator: (v: unknown) => v is T
+): T | undefined {
+  return validator(value) ? value : undefined
+}
+
+/**
+ * Assert that a storage value matches the expected type.
+ *
+ * @typeParam T - The expected type
+ * @param value - The value from storage
+ * @param validator - A type guard function for T
+ * @param message - Error message if validation fails
+ * @returns The value as T
+ * @throws Error if validation fails
+ */
+export function assertStorageValue<T>(
+  value: unknown,
+  validator: (v: unknown) => v is T,
+  message = 'Storage value does not match expected type'
+): T {
+  if (!validator(value)) {
+    throw new Error(message)
+  }
+  return value
+}
+
+// =============================================================================
+// Discriminated Union Helpers
+// =============================================================================
+
+/**
+ * Helper type to create discriminated unions with a type field.
+ *
+ * @typeParam T - The discriminator value
+ * @typeParam P - The payload type
+ *
+ * @example
+ * ```typescript
+ * type UserMessage = DiscriminatedMessage<'user', { userId: string }>
+ * type SystemMessage = DiscriminatedMessage<'system', { code: number }>
+ * type Message = UserMessage | SystemMessage
+ *
+ * function handleMessage(msg: Message) {
+ *   if (msg.type === 'user') {
+ *     console.log(msg.userId) // TypeScript knows this is UserMessage
+ *   }
+ * }
+ * ```
+ */
+export type DiscriminatedMessage<T extends string, P = object> = {
+  readonly type: T
+} & P
+
+/**
+ * Create a type guard for a discriminated union member.
+ *
+ * @typeParam U - The union type
+ * @typeParam T - The discriminator value to match
+ * @param type - The discriminator value
+ * @returns A type guard function
+ *
+ * @example
+ * ```typescript
+ * type Message = { type: 'text'; content: string } | { type: 'image'; url: string }
+ *
+ * const isTextMessage = createDiscriminatorGuard<Message, 'text'>('text')
+ * if (isTextMessage(msg)) {
+ *   console.log(msg.content) // TypeScript knows this is text message
+ * }
+ * ```
+ */
+export function createDiscriminatorGuard<
+  U extends { type: string },
+  T extends U['type']
+>(type: T): (value: U) => value is Extract<U, { type: T }> {
+  return (value): value is Extract<U, { type: T }> => value.type === type
+}
+
+// =============================================================================
+// Safe Casting Utilities
+// =============================================================================
+
+/**
+ * Safely cast a value through unknown with explicit intent.
+ *
+ * This function makes type casting explicit and searchable in the codebase.
+ * Use it when you need to bypass TypeScript's type system due to limitations
+ * in type definitions (e.g., third-party types that don't match runtime behavior).
+ *
+ * @typeParam T - The target type
+ * @param value - The value to cast
+ * @returns The value cast to type T
+ *
+ * @example
+ * ```typescript
+ * // Instead of: value as unknown as TargetType
+ * const result = unsafeCast<TargetType>(value)
+ * ```
+ */
+export function unsafeCast<T>(value: unknown): T {
+  return value as T
+}
+
+/**
+ * Cast with runtime validation.
+ *
+ * Performs a cast with a runtime type check, throwing if validation fails.
+ *
+ * @typeParam T - The target type
+ * @param value - The value to cast
+ * @param validator - Type guard to validate the cast
+ * @param errorMessage - Optional error message
+ * @returns The value cast to type T
+ * @throws Error if validation fails
+ *
+ * @example
+ * ```typescript
+ * const num = safeCast<number>(input, isNumber, 'Expected number')
+ * ```
+ */
+export function safeCast<T>(
+  value: unknown,
+  validator: (v: unknown) => v is T,
+  errorMessage = 'Type validation failed'
+): T {
+  if (!validator(value)) {
+    throw new Error(errorMessage)
+  }
+  return value
+}
+
+// =============================================================================
+// Object Property Helpers
+// =============================================================================
+
+/**
+ * Type-safe property access with default value.
+ *
+ * @typeParam T - The object type
+ * @typeParam K - The key type
+ * @typeParam D - The default value type
+ * @param obj - The object to access
+ * @param key - The property key
+ * @param defaultValue - Default value if property is undefined
+ * @returns The property value or default
+ *
+ * @example
+ * ```typescript
+ * const config = { host: 'localhost' }
+ * const port = getProperty(config, 'port', 3000) // Returns 3000
+ * ```
+ */
+export function getProperty<
+  T extends object,
+  K extends keyof T,
+  D
+>(obj: T, key: K, defaultValue: D): NonNullable<T[K]> | D {
+  const value = obj[key]
+  return (value !== undefined && value !== null) ? value as NonNullable<T[K]> : defaultValue
+}
+
+/**
+ * Check if an object has a specific property.
+ *
+ * @typeParam K - The key type
+ * @param obj - The object to check
+ * @param key - The property key
+ * @returns true if the object has the property
+ */
+export function hasProperty<K extends string>(
+  obj: unknown,
+  key: K
+): obj is Record<K, unknown> {
+  return isPlainObject(obj) && key in obj
+}
+
+/**
+ * Check if an object has specific properties.
+ *
+ * @param obj - The object to check
+ * @param keys - The property keys to check
+ * @returns true if the object has all specified properties
+ */
+export function hasProperties<K extends string>(
+  obj: unknown,
+  keys: K[]
+): obj is Record<K, unknown> {
+  if (!isPlainObject(obj)) return false
+  return keys.every(key => key in obj)
+}