@reasonabletech/utils 0.1.0

package/dist/src/object.d.ts

@@ -0,0 +1,292 @@
+/**
+ * Object utility functions for handling exactOptionalPropertyTypes and clean object construction
+ *
+ * These utilities are designed to work with TypeScript's strict mode and exactOptionalPropertyTypes
+ * configuration, which prevents assigning undefined to optional properties. They provide clean,
+ * type-safe ways to construct objects with conditional properties.
+ *
+ * ## Key Use Cases
+ *
+ * 1. **exactOptionalPropertyTypes compliance** - When you cannot assign undefined to optional properties
+ * 2. **Clean object construction** - Building objects with conditional properties based on runtime values
+ * 3. **API response formatting** - Creating response objects that omit undefined fields
+ * 4. **Configuration objects** - Building config objects where some properties may not be defined
+ *
+ * ## Examples
+ *
+ * ### Basic Conditional Properties
+ * ```typescript
+ * // Instead of this (fails with exactOptionalPropertyTypes):
+ * const badObj = {
+ * name: "test",
+ * description: undefined, // ❌ Error: undefined not assignable to optional property
+ * };
+ *
+ * // Use this:
+ * const goodObj = {
+ * name: "test",
+ * ...includeIf("description", maybeDescription),
+ * };
+ * ```
+ *
+ * ### Multiple Conditional Properties
+ * ```typescript
+ * const config = {
+ * host: "localhost",
+ * port: 3000,
+ * ...includeIfDefined({
+ * ssl: enableSsl ? { cert: certPath, key: keyPath } : undefined,
+ * auth: authConfig, // may be undefined
+ * timeout: customTimeout, // may be undefined
+ * }),
+ * };
+ * ```
+ *
+ * ### API Response Building
+ * ```typescript
+ * function buildApiResponse(user: User) {
+ * return {
+ * id: user.id,
+ * name: user.name,
+ * ...includeIf("email", user.email), // only include if user has email
+ * ...includeIf("avatar", user.avatarUrl), // only include if user has avatar
+ * ...includeIf("lastSeen", user.lastSeenAt ? lastSeenAt.toISOString()), // convert and include if exists
+ * };
+ * }
+ * ```
+ * @module object
+ * @since 1.0.0
+ */
+/**
+ * Conditionally includes a property in an object if the value is not undefined.
+ * This is useful for exactOptionalPropertyTypes compliance where you cannot assign undefined to optional properties.
+ * @param key - The property key to conditionally include
+ * @param value - The value to include, or undefined to omit the property
+ * @returns An empty object if value is undefined, otherwise an object with the key-value pair
+ * @example Basic usage
+ * ```typescript
+ * const obj = {
+ *   required : "value",
+ *   ...includeIf("optional", maybeUndefinedValue),
+ * };
+ * // If maybeUndefinedValue is "hello": { required: "value", optional: "hello" }
+ * // If maybeUndefinedValue is undefined: { required: "value" }
+ * ```
+ * @example API response building
+ * ```typescript
+ * function createUserResponse(user: User) {
+ *   return {
+ *     id: user.id,
+ *     name: user.name,
+ *     ...includeIf("email", user.email),
+ *     ...includeIf("avatar", user.avatar ? avatar.url),
+ *     ...includeIf("lastLogin", user.lastLoginAt?.toISOString()),
+ *   };
+ * }
+ * ```
+ * @example Billing service usage (real project example)
+ * ```typescript
+ * return {
+ *   amount : pricing.amount,
+ *   ...includeIf("setupFee", pricing.setupFee),
+ *   ...includeIf("savings", calculatedSavings),
+ * };
+ * ```
+ */
+export declare function includeIf<K extends string, V>(key: K, value: V | undefined): Record<string, unknown>;
+/**
+ * Conditionally includes multiple properties from an object, omitting any with undefined values.
+ * This creates a new object with only the defined properties.
+ * @param obj - Object containing key-value pairs where values may be undefined
+ * @returns New object containing only the properties where values are not undefined
+ * @example Basic usage
+ * ```typescript
+ * const obj = {
+ *   required: "value",
+ *   ...includeIfDefined({
+ *     optional1: maybeUndefined1,  // included only if not undefined
+ *     optional2: maybeUndefined2,  // included only if not undefined
+ *   }),
+ * };
+ * ```
+ * @example Configuration object building
+ * ```typescript
+ * const config = {
+ *   host: "localhost",
+ *   port: 3000,
+ *   ...includeIfDefined({
+ *     ssl: sslEnabled ? sslEnabled.sslConfig : undefined,
+ *     auth: authConfig, // may be undefined
+ *     timeout: userTimeout, // may be undefined
+ *     retries: retryCount, // may be undefined
+ *   }),
+ * };
+ * ```
+ * @example Form data processing
+ * ```typescript
+ * const formData = {
+ *   name: data.name,
+ *   email: data.email,
+ *   ...includeIfDefined({
+ *     phone: data.phone ? phone.trim() || undefined,
+ *     company : data.company?.trim() || undefined,
+ *     website: data.website ? website.startsWith('http') ? data.website  : undefined,
+ *   }),
+ * };
+ * ```
+ */
+export declare function includeIfDefined<T extends Record<string, unknown>>(obj: T): Record<string, unknown>;
+/**
+ * Omits properties with undefined values from an object.
+ * This is useful for cleaning up objects before assignment when using exactOptionalPropertyTypes.
+ * Note: This only removes undefined values, not other falsy values like null, 0, "", or false.
+ * @param obj - The object to clean of undefined properties
+ * @returns New object with undefined properties removed
+ * @example Basic cleanup
+ * ```typescript
+ * const cleanObj = omitUndefined({
+ *   a: "defined",
+ *   b: undefined,    // ❌ removed
+ *   c: null,         // ✅ preserved (null ≠ undefined)
+ *   d: 0,            // ✅ preserved (falsy but defined)
+ *   e: "",           // ✅ preserved (falsy but defined)
+ *   f: false,        // ✅ preserved (falsy but defined)
+ * });
+ * // Result: { a: "defined", c: null, d: 0, e: "", f: false }
+ * ```
+ * @example API data cleaning
+ * ```typescript
+ * function sanitizeApiResponse(rawData: any) {
+ *   return omitUndefined({
+ *     id: rawData.id,
+ *     name: rawData.name,
+ *     description: rawData.description, // may be undefined
+ *     metadata: rawData.metadata,       // may be undefined
+ *     createdAt: rawData.created_at,
+ *   });
+ * }
+ * ```
+ * @example Before database save
+ * ```typescript
+ * const userUpdate = omitUndefined({
+ *   name: formData.name,
+ *   email: formData.email,
+ *   avatar: formData.avatar,     // only update if provided
+ *   settings: formData.settings, // only update if provided
+ * });
+ * ```
+ */
+export declare function omitUndefined<T extends Record<string, unknown>>(obj: T): Record<string, unknown>;
+/**
+ * Creates an object with conditional properties based on boolean conditions.
+ * Each condition is checked and only truthy conditions include their corresponding properties.
+ * @param conditions - Object where keys are boolean conditions (as strings) and values are objects to include
+ * @returns Object containing properties from all truthy conditions
+ * @example Basic conditional properties
+ * ```typescript
+ * const obj = {
+ *   always: "included",
+ *   ...conditionalProps({
+ *     [String(isEnabled)]: { feature: "enabled" },
+ *     [String(hasPermission)]: { admin: true },
+ *   }),
+ * };
+ * ```
+ * @example Feature flags
+ * ```typescript
+ * const config = {
+ *   baseUrl: "https://api.example.com",
+ *   ...conditionalProps({
+ *     [String(enableLogging)]: { logging: { level: "debug" } },
+ *     [String(enableMetrics)]: { metrics: { endpoint: "/metrics" } },
+ *     [String(enableAuth)]: { auth: { provider: "oauth" } },
+ *   }),
+ * };
+ * ```
+ * @example User permission-based UI
+ * ```typescript
+ * const uiConfig = {
+ *   showProfile: true,
+ *   ...conditionalProps({
+ *     [String(user.isAdmin)]: { showAdminPanel: true },
+ *     [String(user.isPremium)]: { showPremiumFeatures: true },
+ *     [String(user.canEdit)]: { showEditTools: true },
+ *   }),
+ * };
+ * ```
+ */
+export declare function conditionalProps(conditions: Record<string, Record<string, unknown>>): Record<string, unknown>;
+/**
+ * Type-safe way to pick properties from an object, with undefined handling.
+ * Unlike Lodash pick, this preserves exact types and handles undefined values correctly.
+ * Only includes properties that exist in the source object.
+ * @param obj - The source object to pick properties from
+ * @param keys - Array of keys to pick from the object
+ * @returns New object containing only the specified properties
+ * @example Basic property picking
+ * ```typescript
+ * const user = { id: 1, name: "John", email: "john@example.com", password: "secret" };
+ * const publicUser = pick(user, ['id', 'name', 'email']);
+ * // Result: { id: 1, name: "John", email: "john@example.com" }
+ * ```
+ * @example API response filtering
+ * ```typescript
+ * function createPublicProfile(fullUser: FullUser) {
+ *   return pick(fullUser, [
+ *     'id',
+ *     'username',
+ *     'displayName',
+ *     'avatar',
+ *     'joinedAt'
+ *   ]);
+ * }
+ * ```
+ * @example Configuration subset
+ * ```typescript
+ * const fullConfig = { host: "localhost", port: 3000, ssl: true, debug: true, secret: "xxx" };
+ * const clientConfig = pick(fullConfig, ['host', 'port', 'ssl']);
+ * // Result: { host: "localhost", port: 3000, ssl: true }
+ * ```
+ */
+export declare function pick<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: readonly K[]): Pick<T, K>;
+/**
+ * Type-safe way to omit properties from an object, with undefined handling.
+ * Unlike Lodash omit, this preserves exact types and handles undefined values correctly.
+ * Creates a new object excluding the specified properties.
+ * @param obj - The source object to omit properties from
+ * @param keys - Array of keys to omit from the object
+ * @returns New object with the specified properties removed
+ * @example Remove sensitive data
+ * ```typescript
+ * const user = { id: 1, name: "John", email: "john@example.com", password: "secret", ssn: "xxx" };
+ * const safeUser = omit(user, ['password', 'ssn']);
+ * // Result: { id: 1, name: "John", email: "john@example.com" }
+ * ```
+ * @example Remove internal properties
+ * ```typescript
+ * function toApiResponse(internalObj: InternalUser) {
+ *   return omit(internalObj, [
+ *     '_id',
+ *     '_version',
+ *     '_internal',
+ *     'hashedPassword',
+ *     'secretKey'
+ *   ]);
+ * }
+ * ```
+ * @example Configuration sanitization
+ * ```typescript
+ * const fullConfig = {
+ *   host: "localhost",
+ *   port: 3000,
+ *   ssl: true,
+ *   debug: true,
+ *   apiSecret: "xxx",
+ *   dbPassword: "yyy"
+ * };
+ * const publicConfig = omit(fullConfig, ['apiSecret', 'dbPassword']);
+ * // Result: { host: "localhost", port: 3000, ssl: true, debug: true }
+ * ```
+ */
+export declare function omit<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: readonly K[]): Omit<T, K>;
+//# sourceMappingURL=object.d.ts.map

package/dist/src/object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../../src/object.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAC3C,GAAG,EAAE,CAAC,EACN,KAAK,EAAE,CAAC,GAAG,SAAS,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,GAAG,EAAE,CAAC,GACL,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,GAAG,EAAE,CAAC,GACL,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAClD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,EACvE,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,SAAS,CAAC,EAAE,GACjB,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAQZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,EACvE,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,SAAS,CAAC,EAAE,GACjB,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CASZ"}

package/dist/src/result.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Represents a successful Result with a value.
+ * Can be used for type narrowing in tests and assertions.
+ */
+export interface Success<T> {
+    success: true;
+    value: T;
+    error?: undefined;
+}
+/**
+ * Represents a failed Result with an error.
+ * Can be used for type narrowing in tests and assertions.
+ */
+export interface Failure<E> {
+    success: false;
+    error: E;
+    value?: undefined;
+}
+/**
+ * A simplified Result type inspired by Rust's Result.
+ *
+ * This type represents either a successful value (ok) or an error (err).
+ * It is used for consistent error handling across the `@reasonabletech` platform.
+ */
+export type Result<T, E = Error> = Success<T> | Failure<E>;
+/**
+ * Creates a successful Result.
+ * @param value - Optional value to wrap in a successful Result
+ * @returns A successful Result containing the value
+ */
+export declare function ok<T, E = Error>(value: T): Result<T, E>;
+export declare function ok<E = Error>(): Result<void, E>;
+/**
+ * Creates an error Result.
+ * @param error The error to wrap in an error Result
+ * @returns An error Result containing the error
+ */
+export declare function err<T = never, E = Error>(error: E): Result<T, E>;
+/**
+ * Type guard to check if a Result is successful.
+ * @param result The Result to check
+ * @returns True if the Result is successful
+ */
+export declare function isSuccess<T, E = Error>(result: Readonly<Result<T, E>>): result is Success<T>;
+/**
+ * Type guard to check if a Result is an error.
+ * @param result The Result to check
+ * @returns True if the Result is an error
+ */
+export declare function isFailure<T, E = Error>(result: Readonly<Result<T, E>>): result is Failure<E>;
+/**
+ * Wraps a Promise to return a Result.
+ * @param promise The Promise to wrap
+ * @returns A Promise that resolves to a Result
+ */
+export declare function fromPromise<T>(promise: Promise<T>): Promise<Result<T, Error>>;
+/**
+ * Maps a successful Result to a new Result with a transformed value.
+ * @param result The Result to map
+ * @param fn The function to apply to the value
+ * @returns A new Result with the transformed value or the original error
+ */
+export declare function map<T, U, E = Error>(result: Readonly<Result<T, E>>, fn: (value: T) => U): Result<U, E>;
+/**
+ * Maps an error Result to a new Result with a transformed error.
+ * @param result The Result to map
+ * @param fn The function to apply to the error
+ * @returns A new Result with the transformed error or the original value
+ */
+export declare function mapErr<T, E = Error, F = Error>(result: Readonly<Result<T, E>>, fn: (error: E) => F): Result<T, F>;
+/**
+ * Chains a function that returns a Result after a successful Result.
+ * @param result The Result to chain
+ * @param fn The function to apply to the value that returns a Result
+ * @returns The Result returned by the function or the original error
+ */
+export declare function andThen<T, U, E = Error>(result: Readonly<Result<T, E>>, fn: (value: T) => Result<U, E>): Result<U, E>;
+/**
+ * Applies a fallback function to an error Result.
+ * @param result The Result to check
+ * @param fn The function to apply to the error that returns a Result
+ * @returns The original Result if successful, or the Result returned by the function
+ */
+export declare function orElse<T, E = Error, F = Error>(result: Readonly<Result<T, E>>, fn: (error: E) => Result<T, F>): Result<T, F>;
+/**
+ * Unwraps a Result, returning the value or throwing the error.
+ * @param result The Result to unwrap
+ * @returns The value if the Result is successful
+ * @throws {Error} The error if the Result is an error
+ */
+export declare function unwrap<T, E = Error>(result: Readonly<Result<T, E>>): T;
+/**
+ * Unwraps a Result, returning the value or a default value.
+ * @param result The Result to unwrap
+ * @param defaultValue The default value to return if the Result is an error
+ * @returns The value if the Result is successful, or the default value
+ */
+export declare function unwrapOr<T, E = Error>(result: Readonly<Result<T, E>>, defaultValue: T): T;
+/**
+ * Unwraps a Result, returning the value or computing a default value from the error.
+ * @param result The Result to unwrap
+ * @param fn The function to compute the default value from the error
+ * @returns The value if the Result is successful, or the computed default value
+ */
+export declare function unwrapOrElse<T, E = Error>(result: Readonly<Result<T, E>>, fn: (error: E) => T): T;
+/**
+ * Combines an array of Results into a single Result containing an array of values.
+ * If any Result is an error, returns the first error.
+ * @param results Array of Results to combine
+ * @returns A Result containing an array of values or the first error
+ */
+export declare function combine<T, E = Error>(results: ReadonlyArray<Result<T, E>>): Result<T[], E>;
+//# sourceMappingURL=result.d.ts.map

package/dist/src/result.d.ts.map

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

package/dist/src/retry.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Retry utility functions for the `@reasonabletech` platform
+ */
+/**
+ * Core retry configuration fields that have default values
+ */
+interface RetryConfigDefaults {
+    /**
+     * Maximum number of attempts (including the initial attempt)
+     * @default 3
+     */
+    maxAttempts: number;
+    /**
+     * Initial delay in milliseconds before the first retry
+     * @default 1000
+     */
+    initialDelay: number;
+    /**
+     * Maximum delay in milliseconds between retries
+     * @default 30000
+     */
+    maxDelay: number;
+    /**
+     * Multiplier for exponential backoff
+     * @default 2
+     */
+    backoffMultiplier: number;
+    /**
+     * Jitter factor (0-1) to add randomness to delays
+     * @default 0.1
+     */
+    jitterFactor: number;
+    /**
+     * Function to determine if an error should trigger a retry
+     * @default () => true (always retry)
+     */
+    shouldRetry: (error: unknown, attempt: number) => boolean;
+}
+/**
+ * Optional callback hooks for retry operations
+ */
+interface RetryCallbacks {
+    /**
+     * Callback invoked when an attempt fails (before retry decision).
+     * Use this for logging, running interceptors, or other side effects.
+     */
+    onError?: (error: unknown, attempt: number) => void | Promise<void>;
+    /**
+     * Custom delay calculator that overrides the default exponential backoff.
+     * Useful when the error contains retry timing hints (e.g., Retry-After header).
+     */
+    getDelay?: (attempt: number, error: unknown) => number;
+}
+/**
+ * Configuration options for retry operations (all fields optional for user input)
+ * @example
+ * ```typescript
+ * const result = await retry(() => fetchData(), {
+ *   maxAttempts: 5,
+ *   initialDelay: 500,
+ *   onError: (error, attempt) => console.log(`Attempt ${attempt} failed`),
+ * });
+ * ```
+ */
+export interface RetryOptions extends Partial<RetryConfigDefaults>, RetryCallbacks {
+}
+/**
+ * Result of a retry operation
+ */
+export interface RetryResult<T> {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** The result value if successful */
+    value?: T;
+    /** The final error if all attempts failed */
+    error?: unknown;
+    /** Number of attempts made */
+    attempts: number;
+}
+/**
+ * Sleep for the specified number of milliseconds
+ * @param ms - Milliseconds to sleep
+ * @returns Promise that resolves after the delay
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Retry an async operation with exponential backoff and jitter
+ * @param operation - The async operation to retry
+ * @param options - Retry configuration options
+ * @returns Promise resolving to retry result
+ * @example
+ * ```typescript
+ * // Basic retry with defaults (3 attempts, 1s initial delay)
+ * const result = await retry(() => fetchData());
+ *
+ * // Custom configuration with error callback
+ * const result = await retry(() => apiClient.post('/users', userData), {
+ *   maxAttempts: 5,
+ *   initialDelay: 500,
+ *   onError: (error, attempt) => {
+ *     logger.warn('API', `Attempt ${attempt} failed`, { error });
+ *   },
+ * });
+ *
+ * // Use server-provided Retry-After hint
+ * const result = await retry(() => rateLimitedApi.call(), {
+ *   getDelay: (attempt, error) => {
+ *     if (error instanceof ApiError && error.retryAfter) {
+ *       return error.retryAfter; // Use server-provided delay
+ *     }
+ *     return 1000 * Math.pow(2, attempt - 1); // Fallback to exponential
+ *   },
+ * });
+ * ```
+ */
+export declare function retry<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<RetryResult<T>>;
+/**
+ * Retry an operation with polling (fixed interval, no exponential backoff)
+ * @param operation - The async operation to retry
+ * @param maxAttempts - Maximum number of attempts
+ * @param interval - Fixed interval between attempts in milliseconds
+ * @param shouldRetry - Function to determine if retry should continue
+ * @returns Promise resolving to retry result
+ */
+export declare function retryWithPolling<T>(operation: () => Promise<T>, maxAttempts: number, interval: number, shouldRetry?: (error: unknown, attempt: number) => boolean): Promise<RetryResult<T>>;
+/**
+ * Retry an operation with exponential backoff (simplified interface)
+ * This function throws on failure instead of returning a result object.
+ * @param operation - The async operation to retry
+ * @param maxRetries - Maximum number of retries (attempts after the first try, default: 3)
+ * @param baseDelay - Base delay in milliseconds (default: 1000)
+ * @returns Promise resolving to the operation's result
+ * @throws {unknown} The last error if all attempts fail
+ * @example
+ * ```typescript
+ * // Retry up to 3 times with exponential backoff
+ * const result = await retryWithBackoff(() => fetchData(), 3, 500);
+ *
+ * // Use default retries (3) and delay (1000ms)
+ * const user = await retryWithBackoff(() => createUser(userData));
+ * ```
+ */
+export declare function retryWithBackoff<T>(operation: () => Promise<T>, maxRetries?: number, baseDelay?: number): Promise<T>;
+export {};
+//# sourceMappingURL=retry.d.ts.map

package/dist/src/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/retry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,UAAU,mBAAmB;IAC3B;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;CAC3D;AAED;;GAEG;AACH,UAAU,cAAc;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;CACxD;AAOD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YACf,SAAQ,OAAO,CAAC,mBAAmB,CAAC,EAClC,cAAc;CAAG;AAErB;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,qCAAqC;IACrC,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;CAClB;AA8BD;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CA6CzB;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,WAAW,GAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAoB,GACrE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CASzB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,UAAU,GAAE,MAAU,EACtB,SAAS,GAAE,MAAa,GACvB,OAAO,CAAC,CAAC,CAAC,CAYZ"}

package/dist/src/string.d.ts

@@ -0,0 +1,75 @@
+/**
+ * String utility functions
+ */
+/**
+ * Check if a string is empty or only contains whitespace
+ * @param value - The string to check
+ * @returns true if the string is empty, null, undefined, or only whitespace
+ */
+export declare function isEmptyString(value: string | null | undefined): boolean;
+/**
+ * Check if a string is not empty and contains non-whitespace characters
+ * @param value - The string to check
+ * @returns true if the string has content
+ */
+export declare function isNonEmptyString(value: string | null | undefined): value is string;
+/**
+ * Truncate a string to a maximum length with ellipsis
+ * @param str - The string to truncate
+ * @param maxLength - Maximum length (including ellipsis)
+ * @returns Truncated string with ellipsis if needed
+ */
+export declare function truncateString(str: string, maxLength: number): string;
+/**
+ * Capitalize the first letter of a string
+ * @param str - The string to capitalize
+ * @returns String with first letter capitalized
+ */
+export declare function capitalize(str: string): string;
+/**
+ * Create a base64url encoded string
+ * @param data - Data to encode (string or Buffer)
+ * @returns Base64url encoded string (URL-safe, no padding)
+ */
+export declare function encodeBase64Url(data: string | Buffer): string;
+/**
+ * Decode a base64url encoded string
+ * @param encoded - Base64url encoded string
+ * @returns Decoded data as Buffer
+ */
+export declare function decodeBase64Url(encoded: string): Buffer;
+/**
+ * Check if a string is a valid base64url format
+ * @param str - String to validate
+ * @returns True if the string is valid base64url format
+ */
+export declare function isValidBase64Url(str: string): boolean;
+/**
+ * Extract a message string from an unknown error value
+ * @deprecated This utility is unnecessary. The logger accepts `ErrorLike` (unknown)
+ * directly via `logger.error(tag, message, error)`. Pass errors directly to the
+ * logger instead of manually converting to strings.
+ *
+ * See: docs/standards/error-boundary-patterns.md
+ * @example
+ * ```typescript
+ * // ❌ DEPRECATED: Manual error string extraction
+ * try {
+ *   await operation();
+ * } catch (error) {
+ *   logger.error("Component", getErrorMessage(error));
+ * }
+ *
+ * // ✅ CORRECT: Pass error directly to logger
+ * try {
+ *   await operation();
+ * } catch (error) {
+ *   logger.error("Component", "Operation failed", error);
+ * }
+ * ```
+ * @param error - Error value (Error object, string, or other)
+ * @returns Error message string
+ * @internal
+ */
+export declare function getErrorMessage(error: unknown): string;
+//# sourceMappingURL=string.d.ts.map

package/dist/src/string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../../src/string.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAEvE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,KAAK,IAAI,MAAM,CAEjB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK9C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAG7D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKvD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAgBtD"}

package/dist/src/type-guards.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Type guard utilities for common type checking patterns
+ * @module type-guards
+ */
+/**
+ * Type guard to check if value is neither null nor undefined
+ * @template T - The value type
+ * @param value - The value to check
+ * @returns True if value is present (not null or undefined), with type narrowing
+ * @example
+ * ```typescript
+ * // Optional configuration value
+ * const redirectUrl: string | null | undefined = config.redirectUrl;
+ * if (isPresent(redirectUrl)) {
+ *   window.location.href = redirectUrl; // redirectUrl is string
+ * }
+ *
+ * // Database lookup result
+ * const user: User | null = await db.users.findById(id);
+ * if (isPresent(user)) {
+ *   console.log(user.email); // user is User
+ * }
+ * ```
+ */
+export declare function isPresent<T>(value: T | null | undefined): value is T;
+//# sourceMappingURL=type-guards.d.ts.map

package/dist/src/type-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.d.ts","sourceRoot":"","sources":["../../src/type-guards.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,IAAI,CAAC,CAEpE"}