@dotdo/postgres 0.1.0

package/dist/types/utilities.d.ts

@@ -0,0 +1,757 @@
+/**
+ * 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
+ */
+/**
+ * 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>;
+/**
+ * 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;
+/**
+ * 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 declare function success<T>(value: T): Success<T>;
+/**
+ * Creates a failure result.
+ *
+ * @param error - The error
+ * @returns A Failure result
+ */
+export declare function failure<E = Error>(error: E): Failure<E>;
+/**
+ * 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 declare function isSuccess<T, E>(result: Result<T, E>): result is Success<T>;
+/**
+ * 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 declare function isFailure<T, E>(result: Result<T, E>): result is Failure<E>;
+/**
+ * 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;
+/**
+ * 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>>;
+/**
+ * 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];
+/**
+ * Any function type (use sparingly, prefer specific types).
+ */
+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;
+/**
+ * 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 declare function isDefined<T>(value: T | null | undefined): value is T;
+/**
+ * Type guard to check if a value is a string.
+ *
+ * @param value - The value to check
+ * @returns true if value is a string
+ */
+export declare function isString(value: unknown): value is 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 declare function isNumber(value: unknown): value is number;
+/**
+ * Type guard to check if a value is a boolean.
+ *
+ * @param value - The value to check
+ * @returns true if value is a boolean
+ */
+export declare function isBoolean(value: unknown): value is 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 declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Type guard to check if a value is an array.
+ *
+ * @param value - The value to check
+ * @returns true if value is an array
+ */
+export declare function isArray<T = unknown>(value: unknown): value is T[];
+/**
+ * Type guard to check if a value is a function.
+ *
+ * @param value - The value to check
+ * @returns true if value is a function
+ */
+export declare function isFunction(value: unknown): value is AnyFunction;
+/**
+ * Type guard to check if a value is a Promise.
+ *
+ * @param value - The value to check
+ * @returns true if value is a Promise
+ */
+export declare function isPromise<T = unknown>(value: unknown): value is Promise<T>;
+/**
+ * Type guard to check if a value is an Error.
+ *
+ * @param value - The value to check
+ * @returns true if value is an Error
+ */
+export declare function isError(value: unknown): value is Error;
+/**
+ * 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 declare function assertDefined<T>(value: T | null | undefined, message?: string): asserts value is T;
+/**
+ * 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 declare function assert(condition: boolean, message?: string): asserts condition;
+/**
+ * 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 declare function assertNever(value: never, message?: string): never;
+/**
+ * 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;
+/**
+ * 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'];
+/**
+ * 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 declare function toBodyInit(data: Uint8Array): 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 declare function toArrayBuffer(source: ArrayBufferLike | ArrayBufferView): ArrayBuffer;
+/**
+ * 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 declare function isArrayBufferView(value: unknown): value is ArrayBufferView;
+/**
+ * Type guard for checking if a value is a Uint8Array.
+ *
+ * @param value - The value to check
+ * @returns true if value is a Uint8Array
+ */
+export declare function isUint8Array(value: unknown): value is Uint8Array;
+/**
+ * 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 declare function narrowStorageValue<T>(value: unknown, validator: (v: unknown) => v is T): T | 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 declare function assertStorageValue<T>(value: unknown, validator: (v: unknown) => v is T, message?: string): T;
+/**
+ * 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 declare function createDiscriminatorGuard<U extends {
+    type: string;
+}, T extends U['type']>(type: T): (value: U) => value is Extract<U, {
+    type: T;
+}>;
+/**
+ * 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 declare function unsafeCast<T>(value: unknown): 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 declare function safeCast<T>(value: unknown, validator: (v: unknown) => v is T, errorMessage?: string): T;
+/**
+ * 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 declare function getProperty<T extends object, K extends keyof T, D>(obj: T, key: K, defaultValue: D): NonNullable<T[K]> | D;
+/**
+ * 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 declare function hasProperty<K extends string>(obj: unknown, key: K): obj is Record<K, unknown>;
+/**
+ * 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 declare function hasProperties<K extends string>(obj: unknown, keys: K[]): obj is Record<K, unknown>;
+//# sourceMappingURL=utilities.d.ts.map