@dotdo/postgres 0.1.0

package/dist/types/utilities.d.ts.map

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

package/dist/types/utilities.js

@@ -0,0 +1,447 @@
+/**
+ * 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
+ */
+/**
+ * Creates a success result.
+ *
+ * @param value - The success value
+ * @returns A Success result
+ */
+export function success(value) {
+    return { success: true, value };
+}
+/**
+ * Creates a failure result.
+ *
+ * @param error - The error
+ * @returns A Failure result
+ */
+export function failure(error) {
+    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(result) {
+    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(result) {
+    return result.success === false;
+}
+// =============================================================================
+// 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(value) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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(value) {
+    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) {
+    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(value) {
+    return value instanceof Promise || (isPlainObject(value) &&
+        isFunction(value.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) {
+    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(value, message = 'Expected value to be defined') {
+    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, message = 'Assertion failed') {
+    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, message = 'Unexpected value') {
+    throw new Error(`${message}: ${JSON.stringify(value)}`);
+}
+// =============================================================================
+// 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 is a valid BodyInit in all modern environments
+    // The cast is safe because BufferSource (which includes Uint8Array) is part of BodyInit
+    return data;
+}
+/**
+ * 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) {
+    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) {
+    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) {
+    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(value, validator) {
+    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(value, validator, message = 'Storage value does not match expected type') {
+    if (!validator(value)) {
+        throw new Error(message);
+    }
+    return value;
+}
+/**
+ * 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(type) {
+    return (value) => 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(value) {
+    return value;
+}
+/**
+ * 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(value, validator, errorMessage = 'Type validation failed') {
+    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(obj, key, defaultValue) {
+    const value = obj[key];
+    return (value !== undefined && value !== null) ? value : 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(obj, key) {
+    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(obj, keys) {
+    if (!isPlainObject(obj))
+        return false;
+    return keys.every(key => key in obj);
+}
+//# sourceMappingURL=utilities.js.map

package/dist/types/utilities.js.map

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