@parsrun/core 0.1.29 → 0.1.30

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { Runtime, detectRuntime, getRuntimeVersion, isBrowser, isBun, isCloudflare, isDeno, isEdge, isNode, isServer, runtime, runtimeInfo } from './runtime.js';
 export { EnvMode, clearEdgeEnv, createEnvConfig, getEnv, getEnvArray, getEnvBoolean, getEnvFloat, getEnvJson, getEnvMode, getEnvNumber, isDevelopment, isProduction, isTest, requireEnv, setEdgeEnv } from './env.js';
-export { o as BaseTransportOptions, p as BatchTransportOptions, B as Breadcrumb, j as CombinedTransport, C as ConsoleTransport, k as ErrorContext, E as ErrorTransport, n as ErrorUser, g as LogEntry, a as LogLevel, e as LogLevelName, f as LogLevelValue, h as LogTransport, L as Logger, i as LoggerConfig, c as createLogger, d as createRequestLogger, b as logError, l as logger, m as measureTime } from './logger-3oVznpFY.js';
+export { o as BaseTransportOptions, p as BatchTransportOptions, B as Breadcrumb, j as CombinedTransport, C as ConsoleTransport, k as ErrorContext, E as ErrorTransport, n as ErrorUser, g as LogEntry, a as LogLevel, e as LogLevelName, f as LogLevelValue, h as LogTransport, L as Logger, i as LoggerConfig, c as createLogger, d as createRequestLogger, b as logError, l as logger, m as measureTime } from './logger-DrxxwI7C.js';
 export { Decimal, DecimalUtils, decimal } from './decimal.js';
 export { AccessLevel, AuthContext, DeepPartial, IpRestrictions, MembershipPermissions, MembershipStatus, PaginatedResult, PaginationParams, Prettify, RequireAtLeastOne, ResourceRestrictions, Result, Session, Tenant, TenantMembership, TenantStatus, TimeRestrictions, User, err, ok } from './types.js';
 export { AccountLockedError, AuthError, ConflictError, DuplicateError, ForbiddenError, InvalidCredentialsError, MembershipError, MembershipExpiredError, MembershipNotFoundError, NotFoundError, ParsError, RateLimitError, SessionExpiredError, TenantError, TenantNotFoundError, TenantSuspendedError, TwoFactorRequiredError, UnauthorizedError, ValidationError, ValidationErrorDetail } from './errors.js';
@@ -74,7 +74,17 @@ declare function generateId(): string;
  */
 declare function sha256(input: string): Promise<string>;
 /**
- * Hash a string using SHA-256 and return as ArrayBuffer
+ * Hash a string using SHA-256 and return as ArrayBuffer.
+ * Useful when you need the raw bytes for further cryptographic operations.
+ *
+ * @param input - The string to hash
+ * @returns Promise resolving to the raw hash bytes
+ *
+ * @example
+ * ```typescript
+ * const hashBytes = await sha256Bytes('data');
+ * const key = await crypto.subtle.importKey('raw', hashBytes, 'AES-GCM', false, ['encrypt']);
+ * ```
  */
 declare function sha256Bytes(input: string): Promise<ArrayBuffer>;
 /**
@@ -134,11 +144,31 @@ declare function retry<T>(fn: () => Promise<T>, options?: {
     onRetry?: (error: unknown, attempt: number) => void;
 }): Promise<T>;
 /**
- * Omit keys from an object
+ * Create a new object with specified keys omitted.
+ *
+ * @param obj - The source object
+ * @param keys - Array of keys to omit
+ * @returns A new object without the specified keys
+ *
+ * @example
+ * ```typescript
+ * const user = { id: 1, name: 'John', password: 'secret' };
+ * const safe = omit(user, ['password']); // { id: 1, name: 'John' }
+ * ```
  */
 declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
 /**
- * Pick keys from an object
+ * Create a new object with only the specified keys.
+ *
+ * @param obj - The source object
+ * @param keys - Array of keys to include
+ * @returns A new object with only the specified keys
+ *
+ * @example
+ * ```typescript
+ * const user = { id: 1, name: 'John', email: 'john@example.com' };
+ * const subset = pick(user, ['id', 'name']); // { id: 1, name: 'John' }
+ * ```
  */
 declare function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
 /**
@@ -155,47 +185,186 @@ declare function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): P
  */
 declare function deepMerge<T extends object>(target: T, source: Partial<T>): T;
 /**
- * Deep clone an object
+ * Create a deep clone of an object.
+ * Handles nested objects, arrays, and Date instances.
+ *
+ * @param obj - The object to clone
+ * @returns A deep copy of the object
+ *
+ * @example
+ * ```typescript
+ * const original = { nested: { value: 1 }, date: new Date() };
+ * const cloned = deepClone(original);
+ * cloned.nested.value = 2; // original.nested.value is still 1
+ * ```
  */
 declare function deepClone<T>(obj: T): T;
 /**
- * Check if a value is a plain object
+ * Check if a value is a plain object (not an array, Date, etc.).
+ * Useful for type guards and deep merge operations.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a plain object
+ *
+ * @example
+ * ```typescript
+ * isPlainObject({});           // true
+ * isPlainObject({ a: 1 });     // true
+ * isPlainObject([]);           // false
+ * isPlainObject(new Date());   // false
+ * isPlainObject(null);         // false
+ * ```
  */
 declare function isPlainObject(value: unknown): value is Record<string, unknown>;
 /**
- * Check if value is null or undefined
+ * Check if a value is null or undefined.
+ * Provides a type guard for narrowing types.
+ *
+ * @param value - The value to check
+ * @returns True if the value is null or undefined
+ *
+ * @example
+ * ```typescript
+ * if (!isNil(user)) {
+ *   console.log(user.name); // TypeScript knows user is not null/undefined
+ * }
+ * ```
  */
 declare function isNil(value: unknown): value is null | undefined;
 /**
- * Check if value is empty (null, undefined, empty string, empty array, empty object)
+ * Check if a value is empty.
+ * Considers null, undefined, empty strings (including whitespace-only),
+ * empty arrays, and empty objects as empty.
+ *
+ * @param value - The value to check
+ * @returns True if the value is considered empty
+ *
+ * @example
+ * ```typescript
+ * isEmpty(null);       // true
+ * isEmpty('');         // true
+ * isEmpty('  ');       // true
+ * isEmpty([]);         // true
+ * isEmpty({});         // true
+ * isEmpty('hello');    // false
+ * isEmpty([1]);        // false
+ * ```
  */
 declare function isEmpty(value: unknown): boolean;
 /**
- * Normalize email address
+ * Normalize an email address by converting to lowercase and trimming whitespace.
+ * Use this before storing or comparing email addresses.
+ *
+ * @param email - The email address to normalize
+ * @returns The normalized email address
+ *
+ * @example
+ * ```typescript
+ * normalizeEmail('  John.Doe@Example.COM  '); // 'john.doe@example.com'
+ * ```
  */
 declare function normalizeEmail(email: string): string;
 /**
- * Validate email format
+ * Validate that a string is a valid email format.
+ * Uses a simple regex that covers most common email formats.
+ *
+ * @param email - The string to validate
+ * @returns True if the string is a valid email format
+ *
+ * @example
+ * ```typescript
+ * isValidEmail('user@example.com');     // true
+ * isValidEmail('user@sub.example.com'); // true
+ * isValidEmail('invalid');              // false
+ * isValidEmail('user@');                // false
+ * ```
  */
 declare function isValidEmail(email: string): boolean;
 /**
- * Generate a URL-friendly slug from a string
+ * Generate a URL-friendly slug from a string.
+ * Converts to lowercase, replaces non-alphanumeric characters with hyphens,
+ * and removes leading/trailing hyphens.
+ *
+ * @param str - The string to convert
+ * @returns A URL-friendly slug
+ *
+ * @example
+ * ```typescript
+ * slugify('Hello World!');           // 'hello-world'
+ * slugify('My Blog Post Title');     // 'my-blog-post-title'
+ * slugify('  Multiple   Spaces  ');  // 'multiple-spaces'
+ * ```
  */
 declare function slugify(str: string): string;
 /**
- * Truncate string to a maximum length
+ * Truncate a string to a maximum length, adding a suffix if truncated.
+ *
+ * @param str - The string to truncate
+ * @param maxLength - Maximum length including the suffix
+ * @param suffix - String to append when truncated (default: "...")
+ * @returns The truncated string or original if within maxLength
+ *
+ * @example
+ * ```typescript
+ * truncate('Hello World', 8);           // 'Hello...'
+ * truncate('Hello', 10);                // 'Hello'
+ * truncate('Long text here', 10, '>>'); // 'Long tex>>'
+ * ```
  */
 declare function truncate(str: string, maxLength: number, suffix?: string): string;
 /**
- * Debounce a function
+ * Create a debounced version of a function.
+ * The function will only be called after it stops being called for the specified wait period.
+ *
+ * @param fn - The function to debounce
+ * @param wait - Milliseconds to wait before calling the function
+ * @returns A debounced version of the function
+ *
+ * @example
+ * ```typescript
+ * const debouncedSearch = debounce((query: string) => {
+ *   // API call
+ * }, 300);
+ *
+ * // Rapid calls will only trigger one API call after 300ms of inactivity
+ * input.addEventListener('input', (e) => debouncedSearch(e.target.value));
+ * ```
  */
 declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, wait: number): (...args: Parameters<T>) => void;
 /**
- * Throttle a function
+ * Create a throttled version of a function.
+ * The function will be called at most once per wait period.
+ *
+ * @param fn - The function to throttle
+ * @param wait - Minimum milliseconds between function calls
+ * @returns A throttled version of the function
+ *
+ * @example
+ * ```typescript
+ * const throttledScroll = throttle(() => {
+ *   // Handle scroll event
+ * }, 100);
+ *
+ * // Called at most every 100ms during scrolling
+ * window.addEventListener('scroll', throttledScroll);
+ * ```
  */
 declare function throttle<T extends (...args: unknown[]) => unknown>(fn: T, wait: number): (...args: Parameters<T>) => void;
 /**
- * Create a deferred promise
+ * Create a deferred promise with externally accessible resolve/reject functions.
+ * Useful when you need to resolve a promise from outside its executor.
+ *
+ * @returns An object containing the promise and its resolve/reject functions
+ *
+ * @example
+ * ```typescript
+ * const { promise, resolve, reject } = createDeferred<string>();
+ *
+ * // Later, resolve from elsewhere
+ * setTimeout(() => resolve('done!'), 1000);
+ *
+ * const result = await promise; // 'done!'
+ * ```
  */
 declare function createDeferred<T>(): {
     promise: Promise<T>;