typetify 0.1.1

package/dist/logic/index.d.ts

@@ -0,0 +1,531 @@
+/**
+ * Executes a function when condition is truthy.
+ * Replaces: `condition && doSomething()`
+ *
+ * @example
+ * when(user.isAdmin, () => showAdminPanel())
+ * when(count > 0, () => processItems(count))
+ *
+ * // Instead of:
+ * user.isAdmin && showAdminPanel()
+ */
+declare function when<T>(condition: unknown, fn: () => T): T | undefined;
+/**
+ * Returns value when condition is truthy, undefined otherwise.
+ * Replaces: `condition && value`
+ *
+ * @example
+ * const className = whenValue(isActive, 'active')
+ * // Instead of: isActive && 'active'
+ */
+declare function whenValue<T>(condition: unknown, value: T): T | undefined;
+
+/**
+ * Executes a function unless condition is truthy.
+ * Replaces: `!condition && doSomething()`
+ *
+ * @example
+ * unless(user.isBlocked, () => allowAccess())
+ *
+ * // Instead of:
+ * !user.isBlocked && allowAccess()
+ */
+declare function unless<T>(condition: unknown, fn: () => T): T | undefined;
+/**
+ * Returns value unless condition is truthy, undefined otherwise.
+ *
+ * @example
+ * const message = unlessValue(isHidden, 'Hello!')
+ */
+declare function unlessValue<T>(condition: unknown, value: T): T | undefined;
+
+/**
+ * Returns one of two values based on a condition.
+ * Replaces: `condition ? valueA : valueB`
+ *
+ * @example
+ * const status = ifElse(isOnline, 'Online', 'Offline')
+ * const greeting = ifElse(user.name, `Hello ${user.name}`, 'Hello Guest')
+ *
+ * // Instead of:
+ * const status = isOnline ? 'Online' : 'Offline'
+ */
+declare function ifElse<T, F>(condition: unknown, whenTrue: T, whenFalse: F): T | F;
+/**
+ * Lazy version - executes functions instead of evaluating values.
+ * Useful when values are expensive to compute.
+ *
+ * @example
+ * const result = ifElseLazy(
+ *   shouldCompute,
+ *   () => expensiveComputation(),
+ *   () => cachedValue
+ * )
+ */
+declare function ifElseLazy<T, F>(condition: unknown, whenTrue: () => T, whenFalse: () => F): T | F;
+
+/**
+ * Pattern matching with multiple conditions.
+ * Replaces nested ternaries or switch statements.
+ *
+ * @example
+ * const message = cond(
+ *   [score >= 90, 'Excellent'],
+ *   [score >= 70, 'Good'],
+ *   [score >= 50, 'Pass'],
+ *   [true, 'Fail'] // default
+ * )
+ *
+ * // Instead of:
+ * const message = score >= 90 ? 'Excellent'
+ *   : score >= 70 ? 'Good'
+ *   : score >= 50 ? 'Pass'
+ *   : 'Fail'
+ */
+declare function cond<T>(...pairs: readonly [condition: unknown, value: T][]): T | undefined;
+/**
+ * Lazy version - evaluates functions instead of values.
+ *
+ * @example
+ * const result = condLazy(
+ *   [isAdmin, () => getAdminData()],
+ *   [isUser, () => getUserData()],
+ *   [true, () => getGuestData()]
+ * )
+ */
+declare function condLazy<T>(...pairs: readonly [condition: unknown, fn: () => T][]): T | undefined;
+/**
+ * Cond with predicate functions for more complex matching.
+ *
+ * @example
+ * const category = condBy(
+ *   age,
+ *   [n => n < 13, 'child'],
+ *   [n => n < 20, 'teen'],
+ *   [n => n < 60, 'adult'],
+ *   [() => true, 'senior']
+ * )
+ */
+declare function condBy<V, T>(value: V, ...pairs: readonly [predicate: (v: V) => boolean, result: T][]): T | undefined;
+
+/**
+ * Type-safe pattern matching on values.
+ * Replaces switch statements with exhaustive checking.
+ *
+ * @example
+ * type Status = 'pending' | 'success' | 'error'
+ *
+ * const message = matchValue(status, {
+ *   pending: 'Loading...',
+ *   success: 'Done!',
+ *   error: 'Failed!',
+ * })
+ *
+ * // Instead of:
+ * let message: string
+ * switch (status) {
+ *   case 'pending': message = 'Loading...'; break
+ *   case 'success': message = 'Done!'; break
+ *   case 'error': message = 'Failed!'; break
+ * }
+ */
+declare function matchValue<T extends string | number, R>(value: T, cases: Record<T, R>): R;
+/**
+ * Pattern matching with a default case.
+ *
+ * @example
+ * const icon = matchWithDefault(status, {
+ *   success: '✓',
+ *   error: '✗',
+ * }, '?')
+ */
+declare function matchWithDefault<T extends string | number, R, D>(value: T, cases: Partial<Record<T, R>>, defaultValue: D): R | D;
+/**
+ * Lazy pattern matching - executes functions.
+ *
+ * @example
+ * const result = matchLazy(action.type, {
+ *   increment: () => state + 1,
+ *   decrement: () => state - 1,
+ *   reset: () => 0,
+ * })
+ */
+declare function matchLazy<T extends string | number, R>(value: T, cases: Record<T, () => R>): R;
+/**
+ * Pattern matching with type guards.
+ *
+ * @example
+ * const result = matchType(value, [
+ *   [isString, (s) => s.toUpperCase()],
+ *   [isNumber, (n) => n * 2],
+ *   [isArray, (arr) => arr.length],
+ * ])
+ */
+declare function matchType<T, R>(value: T, matchers: readonly [guard: (v: T) => boolean, handler: (v: T) => R][]): R | undefined;
+
+/**
+ * Returns the last value if all values are truthy, otherwise the first falsy value.
+ * Replaces: `a && b && c`
+ *
+ * @example
+ * const result = and(user, user.isActive, user.hasPermission)
+ * // Instead of: user && user.isActive && user.hasPermission
+ *
+ * // With callback
+ * const data = and(isReady, hasData, () => processData())
+ */
+declare function and<T>(...values: readonly T[]): T | undefined;
+/**
+ * Returns true if all values are truthy.
+ *
+ * @example
+ * if (allTrue(isLoggedIn, hasPermission, isActive)) {
+ *   // proceed
+ * }
+ */
+declare function allTrue(...values: readonly unknown[]): boolean;
+/**
+ * Returns the result of the callback if all conditions are truthy.
+ *
+ * @example
+ * const result = andThen(
+ *   [user, user?.isAdmin, user?.canEdit],
+ *   () => editDocument()
+ * )
+ */
+declare function andThen<T>(conditions: readonly unknown[], fn: () => T): T | undefined;
+
+/**
+ * Returns the first truthy value, or the last value if none are truthy.
+ * Replaces: `a || b || c`
+ *
+ * @example
+ * const name = or(user.nickname, user.firstName, user.email, 'Anonymous')
+ * // Instead of: user.nickname || user.firstName || user.email || 'Anonymous'
+ */
+declare function or<T>(...values: readonly T[]): T | undefined;
+/**
+ * Returns true if any value is truthy.
+ *
+ * @example
+ * if (anyTrue(isAdmin, isModerator, isOwner)) {
+ *   // has elevated permissions
+ * }
+ */
+declare function anyTrue(...values: readonly unknown[]): boolean;
+/**
+ * Returns the result of the callback if any condition is truthy.
+ *
+ * @example
+ * const result = orThen(
+ *   [isAdmin, isModerator],
+ *   () => showModTools()
+ * )
+ */
+declare function orThen<T>(conditions: readonly unknown[], fn: () => T): T | undefined;
+
+/**
+ * Negates a value.
+ * Replaces: `!value`
+ *
+ * @example
+ * const isInactive = not(user.isActive)
+ *
+ * // Useful in functional composition
+ * users.filter(not(isAdmin))
+ */
+declare function not<T>(value: T): boolean;
+/**
+ * Creates a negated predicate function.
+ *
+ * @example
+ * const isNotEmpty = notFn(isEmpty)
+ * const validItems = items.filter(isNotEmpty)
+ */
+declare function notFn<T extends readonly unknown[]>(predicate: (...args: T) => boolean): (...args: T) => boolean;
+
+/**
+ * Returns the first non-nullish value (not null or undefined).
+ * Replaces: `a ?? b ?? c`
+ *
+ * @example
+ * const value = coalesce(config.timeout, defaultConfig.timeout, 5000)
+ * // Instead of: config.timeout ?? defaultConfig.timeout ?? 5000
+ *
+ * // Handles 0 and '' correctly (unlike ||)
+ * coalesce(0, 10) // 0
+ * coalesce('', 'default') // ''
+ */
+declare function coalesce<T>(...values: readonly (T | null | undefined)[]): T | undefined;
+/**
+ * Lazy version - evaluates functions only if needed.
+ *
+ * @example
+ * const config = coalesceLazy(
+ *   () => getUserConfig(),
+ *   () => getDefaultConfig(),
+ *   () => ({ timeout: 5000 })
+ * )
+ */
+declare function coalesceLazy<T>(...fns: readonly (() => T | null | undefined)[]): T | undefined;
+
+/**
+ * Returns the value if it's not nullish, otherwise returns the default.
+ * Replaces: `value ?? defaultValue`
+ *
+ * @example
+ * const timeout = defaultTo(config.timeout, 5000)
+ * // Instead of: config.timeout ?? 5000
+ */
+declare function defaultTo<T, D>(value: T | null | undefined, defaultValue: D): T | D;
+/**
+ * Lazy version - evaluates default only if needed.
+ *
+ * @example
+ * const user = defaultToLazy(cachedUser, () => fetchUser())
+ */
+declare function defaultToLazy<T, D>(value: T | null | undefined, getDefault: () => D): T | D;
+/**
+ * Returns the value if it passes the predicate, otherwise returns the default.
+ *
+ * @example
+ * const validAge = defaultToIf(age, n => n >= 0 && n <= 150, 0)
+ */
+declare function defaultToIf<T, D>(value: T, predicate: (v: T) => boolean, defaultValue: D): T | D;
+/**
+ * Returns the value if it's not empty (null, undefined, '', [], {}), otherwise returns the default.
+ *
+ * @example
+ * const name = defaultToIfEmpty(user.name, 'Anonymous')
+ */
+declare function defaultToIfEmpty<T, D>(value: T | null | undefined, defaultValue: D): T | D;
+
+/**
+ * Returns the first truthy value from an array.
+ *
+ * @example
+ * const source = firstTruthy([null, '', 0, 'hello', 'world'])
+ * // 'hello'
+ */
+declare function firstTruthy<T>(values: readonly T[]): T | undefined;
+/**
+ * Returns the first value that passes the predicate.
+ *
+ * @example
+ * const validEmail = firstWhere(
+ *   [user.email, user.backupEmail, 'default@example.com'],
+ *   isValidEmail
+ * )
+ */
+declare function firstWhere<T>(values: readonly T[], predicate: (value: T) => boolean): T | undefined;
+/**
+ * Returns the first non-nullish value from an array.
+ *
+ * @example
+ * const value = firstDefined([null, undefined, 0, '', false])
+ * // 0 (first non-nullish value)
+ */
+declare function firstDefined<T>(values: readonly (T | null | undefined)[]): T | undefined;
+
+/**
+ * Returns true if all values are truthy.
+ *
+ * @example
+ * if (allTruthy([user, user.isActive, user.hasPermission])) {
+ *   // proceed
+ * }
+ */
+declare function allTruthy(values: readonly unknown[]): boolean;
+/**
+ * Returns true if all values pass the predicate.
+ *
+ * @example
+ * const allValid = allWhere([email1, email2, email3], isValidEmail)
+ */
+declare function allWhere<T>(values: readonly T[], predicate: (value: T) => boolean): boolean;
+/**
+ * Returns true if all values are defined (not null or undefined).
+ *
+ * @example
+ * if (allDefined([user, user.profile, user.profile.settings])) {
+ *   // safe to access user.profile.settings
+ * }
+ */
+declare function allDefined(values: readonly unknown[]): boolean;
+
+/**
+ * Safely gets a nested property value using a path.
+ * Replaces: `obj?.a?.b?.c`
+ *
+ * @example
+ * const city = get(user, 'address', 'city')
+ * // Instead of: user?.address?.city
+ *
+ * const firstItem = get(data, 'items', 0, 'name')
+ * // Instead of: data?.items?.[0]?.name
+ */
+declare function get<T>(obj: unknown, ...path: readonly PropertyKey[]): T | undefined;
+/**
+ * Type-safe get for known object structures.
+ *
+ * @example
+ * interface User { profile: { name: string } }
+ * const name = getTyped<User, string>(user, ['profile', 'name'])
+ */
+declare function getTyped<T, R>(obj: T, path: readonly PropertyKey[]): R | undefined;
+/**
+ * Gets a value using a dot-notation path string.
+ *
+ * @example
+ * const city = getPath(user, 'address.city')
+ * const item = getPath(data, 'items.0.name')
+ */
+declare function getPath<T>(obj: unknown, path: string): T | undefined;
+
+/**
+ * Safely gets a nested property value, returning a default if not found.
+ * Replaces: `obj?.a?.b?.c ?? defaultValue`
+ *
+ * @example
+ * const city = getOr(user, 'Unknown', 'address', 'city')
+ * // Instead of: user?.address?.city ?? 'Unknown'
+ */
+declare function getOr<T>(obj: unknown, defaultValue: T, ...path: readonly PropertyKey[]): T;
+/**
+ * Gets a value using dot-notation path, with default.
+ *
+ * @example
+ * const city = getPathOr(user, 'Unknown', 'address.city')
+ */
+declare function getPathOr<T>(obj: unknown, defaultValue: T, path: string): T;
+/**
+ * Lazy version - computes default only if needed.
+ *
+ * @example
+ * const config = getOrLazy(settings, () => computeDefault(), 'theme', 'colors')
+ */
+declare function getOrLazy<T>(obj: unknown, getDefault: () => T, ...path: readonly PropertyKey[]): T;
+
+/**
+ * Tries to get a value, catching any errors.
+ * Useful for accessing properties that might throw.
+ *
+ * @example
+ * const value = tryGet(() => JSON.parse(str).data.value)
+ * // Instead of: try { JSON.parse(str).data.value } catch { undefined }
+ */
+declare function tryGet<T>(fn: () => T): T | undefined;
+/**
+ * Tries to get a value, returning default on error.
+ *
+ * @example
+ * const config = tryGetOr(() => JSON.parse(str), defaultConfig)
+ */
+declare function tryGetOr<T>(fn: () => T, defaultValue: T): T;
+/**
+ * Tries to get a value, returning Result type.
+ *
+ * @example
+ * const result = tryGetResult(() => riskyOperation())
+ * if (result.ok) {
+ *   console.log(result.value)
+ * } else {
+ *   console.error(result.error)
+ * }
+ */
+declare function tryGetResult<T>(fn: () => T): {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: unknown;
+};
+
+/**
+ * Wraps an object to make all property access safe (returns undefined instead of throwing).
+ * Creates a proxy that handles undefined/null gracefully.
+ *
+ * @example
+ * const safeUser = safe(user)
+ * const city = safeUser.address.city.name // undefined if any part is missing
+ *
+ * // Instead of:
+ * const city = user?.address?.city?.name
+ */
+declare function safe<T extends object>(obj: T | null | undefined): SafeProxy<T>;
+/**
+ * Unwraps a safe proxy to get the actual value (or undefined).
+ *
+ * @example
+ * const safeUser = safe(user)
+ * const city = unwrap(safeUser.address.city) // string | undefined
+ */
+declare function unwrap<T>(value: T): T | undefined;
+type SafeProxy<T> = T extends object ? {
+    [K in keyof T]: SafeProxy<T[K]>;
+} : T | undefined;
+
+/**
+ * Chains operations on a value, stopping if any returns null/undefined.
+ * Replaces: `a?.method1()?.method2()?.method3()`
+ *
+ * @example
+ * const result = chain(user)
+ *   .map(u => u.profile)
+ *   .map(p => p.settings)
+ *   .map(s => s.theme)
+ *   .value()
+ *
+ * // Instead of:
+ * const result = user?.profile?.settings?.theme
+ */
+declare function chain<T>(value: T | null | undefined): Chain<T>;
+interface Chain<T> {
+    map<U>(fn: (v: T) => U | null | undefined): Chain<U>;
+    flatMap<U>(fn: (v: T) => Chain<U>): Chain<U>;
+    filter(predicate: (v: T) => boolean): Chain<T>;
+    tap(fn: (v: T) => void): Chain<T>;
+    value(): T | undefined;
+    valueOr<D>(defaultValue: D): T | D;
+    valueOrThrow(message?: string): T;
+}
+
+/**
+ * Calls a method on an object only if the object exists.
+ * Replaces: `obj?.method(args)`
+ *
+ * @example
+ * optional(user, u => u.getName())
+ * optional(array, a => a.map(x => x * 2))
+ *
+ * // Instead of:
+ * user?.getName()
+ * array?.map(x => x * 2)
+ */
+declare function optional<T, R>(value: T | null | undefined, fn: (v: T) => R): R | undefined;
+/**
+ * Calls a method with a default value if the object doesn't exist.
+ *
+ * @example
+ * const length = optionalOr(str, s => s.length, 0)
+ * // Instead of: str?.length ?? 0
+ */
+declare function optionalOr<T, R, D>(value: T | null | undefined, fn: (v: T) => R, defaultValue: D): R | D;
+/**
+ * Applies multiple optional operations in sequence.
+ *
+ * @example
+ * const result = optionalChain(
+ *   user,
+ *   u => u.profile,
+ *   p => p.settings,
+ *   s => s.theme
+ * )
+ * // Instead of: user?.profile?.settings?.theme
+ */
+declare function optionalChain<T, A>(value: T | null | undefined, fn1: (v: T) => A | null | undefined): A | undefined;
+declare function optionalChain<T, A, B>(value: T | null | undefined, fn1: (v: T) => A | null | undefined, fn2: (v: A) => B | null | undefined): B | undefined;
+declare function optionalChain<T, A, B, C>(value: T | null | undefined, fn1: (v: T) => A | null | undefined, fn2: (v: A) => B | null | undefined, fn3: (v: B) => C | null | undefined): C | undefined;
+declare function optionalChain<T, A, B, C, D>(value: T | null | undefined, fn1: (v: T) => A | null | undefined, fn2: (v: A) => B | null | undefined, fn3: (v: B) => C | null | undefined, fn4: (v: C) => D | null | undefined): D | undefined;
+
+export { type Chain, allDefined, allTrue, allTruthy, allWhere, and, andThen, anyTrue, chain, coalesce, coalesceLazy, cond, condBy, condLazy, defaultTo, defaultToIf, defaultToIfEmpty, defaultToLazy, firstDefined, firstTruthy, firstWhere, get, getOr, getOrLazy, getPath, getPathOr, getTyped, ifElse, ifElseLazy, matchLazy, matchType, matchValue, matchWithDefault, not, notFn, optional, optionalChain, optionalOr, or, orThen, safe, tryGet, tryGetOr, tryGetResult, unless, unlessValue, unwrap, when, whenValue };