typetify 0.1.1

package/dist/narrowing/index.d.mts

@@ -0,0 +1,429 @@
+/**
+ * Core types for type narrowing utilities
+ */
+/**
+ * A type guard function that narrows T to S
+ */
+type TypeGuard<T, S extends T> = (value: T) => value is S;
+/**
+ * A refinement function that narrows T to S with additional context
+ */
+type Refinement<T, S extends T> = (value: T, index: number, array: readonly T[]) => value is S;
+/**
+ * Extracts the narrowed type from a type guard
+ */
+type GuardedType<G> = G extends TypeGuard<unknown, infer S> ? S : never;
+/**
+ * Falsy values in JavaScript
+ */
+type Falsy = false | 0 | 0n | '' | null | undefined;
+/**
+ * Removes falsy types from a union
+ */
+type Truthy<T> = Exclude<T, Falsy>;
+/**
+ * NonNullable but preserves the original type structure
+ */
+type Defined<T> = T extends null | undefined ? never : T;
+
+/**
+ * Filters an array removing null and undefined values with proper type narrowing.
+ *
+ * This solves the pain point where `array.filter(x => x != null)` returns
+ * `(T | null | undefined)[]` instead of `T[]`.
+ *
+ * @example
+ * const users: (User | null | undefined)[] = [user1, null, user2, undefined]
+ * const defined = filterDefined(users)
+ * // Type: User[] (not (User | null | undefined)[])
+ *
+ * @example
+ * // Works with complex union types
+ * const mixed: (string | number | null)[] = ['a', 1, null, 'b', 2]
+ * const result = filterDefined(mixed)
+ * // Type: (string | number)[]
+ */
+declare function filterDefined<T>(array: readonly (T | null | undefined)[]): Defined<T>[];
+/**
+ * Curried version for use in pipelines
+ *
+ * @example
+ * pipe(
+ *   users,
+ *   filterDefinedFn(),
+ *   map(u => u.name)
+ * )
+ */
+declare function filterDefinedFn<T>(): (array: readonly (T | null | undefined)[]) => Defined<T>[];
+
+/**
+ * Filters an array removing all falsy values with proper type narrowing.
+ *
+ * Removes: false, 0, 0n, '', null, undefined
+ *
+ * @example
+ * const values: (string | number | null | undefined | false)[] =
+ *   ['hello', 0, '', null, 'world', false, 42]
+ *
+ * const truthy = filterTruthy(values)
+ * // Type: (string | number)[]
+ * // Value: ['hello', 'world', 42]
+ *
+ * @example
+ * // Useful for conditional rendering arrays
+ * const items = filterTruthy([
+ *   showHeader && <Header />,
+ *   <Content />,
+ *   showFooter && <Footer />
+ * ])
+ */
+declare function filterTruthy<T>(array: readonly T[]): Truthy<T>[];
+/**
+ * Curried version for use in pipelines
+ */
+declare function filterTruthyFn<T>(): (array: readonly T[]) => Truthy<T>[];
+
+/**
+ * Filters an array using a type guard with proper type narrowing.
+ *
+ * This is the generic solution for filtering with any type guard.
+ *
+ * @example
+ * const items: unknown[] = [1, 'hello', 2, 'world', null]
+ *
+ * const strings = filterByGuard(items, isString)
+ * // Type: string[]
+ *
+ * const numbers = filterByGuard(items, isNumber)
+ * // Type: number[]
+ *
+ * @example
+ * // With custom type guards
+ * interface Admin { role: 'admin'; permissions: string[] }
+ * interface User { role: 'user' }
+ * type Person = Admin | User
+ *
+ * const isAdmin = (p: Person): p is Admin => p.role === 'admin'
+ * const admins = filterByGuard(people, isAdmin)
+ * // Type: Admin[]
+ */
+declare function filterByGuard<T, S extends T>(array: readonly T[], guard: TypeGuard<T, S>): S[];
+/**
+ * Filters with a refinement function that has access to index and array
+ */
+declare function filterByRefinement<T, S extends T>(array: readonly T[], refinement: Refinement<T, S>): S[];
+/**
+ * Creates a filter function from a type guard for use in pipelines
+ *
+ * @example
+ * pipe(
+ *   items,
+ *   filterBy(isString),
+ *   map(s => s.toUpperCase())
+ * )
+ */
+declare function filterBy<T, S extends T>(guard: TypeGuard<T, S>): (array: readonly T[]) => S[];
+/**
+ * Partitions an array by a type guard into [matches, nonMatches]
+ *
+ * @example
+ * const [strings, others] = partitionByGuard(items, isString)
+ * // strings: string[]
+ * // others: Exclude<typeof items[number], string>[]
+ */
+declare function partitionByGuard<T, S extends T>(array: readonly T[], guard: TypeGuard<T, S>): [S[], Exclude<T, S>[]];
+
+/**
+ * Asserts that a value matches a type guard, throwing if it doesn't.
+ * This is an assertion function that narrows the type in the current scope.
+ *
+ * @example
+ * function processUser(data: unknown) {
+ *   assertType(data, isUser, 'Expected user data')
+ *   // After this line, data is typed as User
+ *   console.log(data.name)
+ * }
+ *
+ * @example
+ * // With custom error
+ * assertType(response, isApiResponse, () =>
+ *   new ValidationError('Invalid API response', response)
+ * )
+ */
+declare function assertType<T, S extends T>(value: T, guard: TypeGuard<T, S>, message?: string | (() => Error)): asserts value is S;
+/**
+ * Asserts that a value is defined (not null or undefined)
+ *
+ * @example
+ * const user: User | null = findUser(id)
+ * assertDefined(user, `User ${id} not found`)
+ * // After this line, user is typed as User
+ * console.log(user.name)
+ */
+declare function assertDefined<T>(value: T | null | undefined, message?: string): asserts value is T;
+/**
+ * Asserts that a value is not null
+ */
+declare function assertNotNull<T>(value: T | null, message?: string): asserts value is T;
+/**
+ * Asserts a condition and narrows the type
+ *
+ * @example
+ * function process(value: string | number) {
+ *   assertCondition(typeof value === 'string', 'Expected string')
+ *   // value is now string
+ *   return value.toUpperCase()
+ * }
+ */
+declare function assertCondition(condition: boolean, message?: string): asserts condition;
+/**
+ * Creates a type assertion function from a type guard
+ *
+ * @example
+ * const assertUser = createAssertion(isUser, 'Expected User')
+ *
+ * function process(data: unknown) {
+ *   assertUser(data)
+ *   // data is now User
+ * }
+ */
+declare function createAssertion<T, S extends T>(guard: TypeGuard<T, S>, defaultMessage?: string): (value: T, message?: string) => asserts value is S;
+
+/**
+ * Narrows a discriminated union by its discriminant property.
+ *
+ * @example
+ * type Event =
+ *   | { type: 'click'; x: number; y: number }
+ *   | { type: 'keypress'; key: string }
+ *   | { type: 'scroll'; delta: number }
+ *
+ * const event: Event = getEvent()
+ *
+ * if (narrowUnion(event, 'type', 'click')) {
+ *   // event is { type: 'click'; x: number; y: number }
+ *   console.log(event.x, event.y)
+ * }
+ */
+declare function narrowUnion<T extends Record<K, PropertyKey>, K extends keyof T, V extends T[K]>(value: T, key: K, expected: V): value is Extract<T, Record<K, V>>;
+/**
+ * Creates a type guard for a specific discriminant value
+ *
+ * @example
+ * type Result = { status: 'ok'; data: string } | { status: 'error'; message: string }
+ *
+ * const isOk = createDiscriminantGuard<Result>()('status', 'ok')
+ * const isError = createDiscriminantGuard<Result>()('status', 'error')
+ *
+ * if (isOk(result)) {
+ *   console.log(result.data)
+ * }
+ */
+declare function createDiscriminantGuard<T extends Record<string, unknown>>(): <K extends keyof T, V extends T[K]>(key: K, value: V) => ((obj: T) => obj is Extract<T, Record<K, V>>);
+/**
+ * Exhaustive switch helper for discriminated unions
+ *
+ * @example
+ * type Shape =
+ *   | { kind: 'circle'; radius: number }
+ *   | { kind: 'square'; side: number }
+ *   | { kind: 'rectangle'; width: number; height: number }
+ *
+ * function area(shape: Shape): number {
+ *   return switchUnion(shape, 'kind', {
+ *     circle: (s) => Math.PI * s.radius ** 2,
+ *     square: (s) => s.side ** 2,
+ *     rectangle: (s) => s.width * s.height,
+ *   })
+ * }
+ */
+declare function switchUnion<T extends Record<K, string>, K extends keyof T, R>(value: T, key: K, handlers: {
+    [V in T[K]]: (value: Extract<T, Record<K, V>>) => R;
+}): R;
+/**
+ * Type-safe exhaustive check that ensures all union cases are handled
+ *
+ * @example
+ * type Status = 'pending' | 'success' | 'error'
+ *
+ * function handleStatus(status: Status) {
+ *   switch (status) {
+ *     case 'pending': return 'Loading...'
+ *     case 'success': return 'Done!'
+ *     case 'error': return 'Failed'
+ *     default: return exhaustiveCheck(status)
+ *   }
+ * }
+ */
+declare function exhaustiveCheck(value: never, message?: string): never;
+
+/**
+ * Excludes null from a value's type at runtime and compile time.
+ * Throws if the value is null.
+ *
+ * @example
+ * const element: HTMLElement | null = document.getElementById('app')
+ * const el = excludeNull(element, 'App element not found')
+ * // el is HTMLElement
+ */
+declare function excludeNull<T>(value: T | null, message?: string): T;
+/**
+ * Excludes undefined from a value's type at runtime and compile time.
+ * Throws if the value is undefined.
+ */
+declare function excludeUndefined<T>(value: T | undefined, message?: string): T;
+/**
+ * Excludes null and undefined from a value's type.
+ * Throws if the value is null or undefined.
+ */
+declare function excludeNullish<T>(value: T | null | undefined, message?: string): T;
+/**
+ * Returns the value if defined, otherwise returns the default.
+ * Type-safe alternative to the nullish coalescing operator with better inference.
+ *
+ * @example
+ * const config: Config | undefined = loadConfig()
+ * const safeConfig = withDefault(config, defaultConfig)
+ * // safeConfig is Config (not Config | undefined)
+ */
+declare function withDefault<T>(value: T | null | undefined, defaultValue: T): T;
+/**
+ * Returns the value if defined, otherwise calls the factory function.
+ * Useful when the default value is expensive to compute.
+ *
+ * @example
+ * const cached = withDefaultLazy(cache.get(key), () => computeExpensiveValue())
+ */
+declare function withDefaultLazy<T>(value: T | null | undefined, factory: () => T): T;
+/**
+ * Maps a nullable value, returning null/undefined if the input is null/undefined.
+ *
+ * @example
+ * const user: User | null = findUser(id)
+ * const name = mapNullable(user, u => u.name)
+ * // name is string | null
+ */
+declare function mapNullable<T, U>(value: T | null | undefined, fn: (value: T) => U): U | null | undefined;
+/**
+ * Chains nullable operations, similar to optional chaining but with functions.
+ *
+ * @example
+ * const result = chainNullable(
+ *   user,
+ *   u => u.profile,
+ *   p => p.settings,
+ *   s => s.theme
+ * )
+ * // result is Theme | null | undefined
+ */
+declare function chainNullable<T, A>(value: T | null | undefined, fn1: (v: T) => A | null | undefined): A | null | undefined;
+declare function chainNullable<T, A, B>(value: T | null | undefined, fn1: (v: T) => A | null | undefined, fn2: (v: A) => B | null | undefined): B | null | undefined;
+declare function chainNullable<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 | null | undefined;
+declare function chainNullable<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 | null | undefined;
+
+/**
+ * Refines a type by applying multiple type guards in sequence.
+ * Each guard further narrows the type.
+ *
+ * @example
+ * const isPositiveNumber = refine(
+ *   isNumber,
+ *   (n): n is number => n > 0
+ * )
+ *
+ * if (isPositiveNumber(value)) {
+ *   // value is number and > 0
+ * }
+ */
+declare function refine<T, S extends T, R extends S>(guard1: TypeGuard<T, S>, guard2: TypeGuard<S, R>): TypeGuard<T, R>;
+declare function refine<T, S extends T, R extends S, Q extends R>(guard1: TypeGuard<T, S>, guard2: TypeGuard<S, R>, guard3: TypeGuard<R, Q>): TypeGuard<T, Q>;
+/**
+ * Combines multiple type guards with OR logic.
+ * Returns true if any guard matches.
+ *
+ * @example
+ * const isStringOrNumber = oneOf(isString, isNumber)
+ *
+ * if (isStringOrNumber(value)) {
+ *   // value is string | number
+ * }
+ */
+declare function oneOf<T, S1 extends T>(guard1: TypeGuard<T, S1>): TypeGuard<T, S1>;
+declare function oneOf<T, S1 extends T, S2 extends T>(guard1: TypeGuard<T, S1>, guard2: TypeGuard<T, S2>): TypeGuard<T, S1 | S2>;
+declare function oneOf<T, S1 extends T, S2 extends T, S3 extends T>(guard1: TypeGuard<T, S1>, guard2: TypeGuard<T, S2>, guard3: TypeGuard<T, S3>): TypeGuard<T, S1 | S2 | S3>;
+declare function oneOf<T, S1 extends T, S2 extends T, S3 extends T, S4 extends T>(guard1: TypeGuard<T, S1>, guard2: TypeGuard<T, S2>, guard3: TypeGuard<T, S3>, guard4: TypeGuard<T, S4>): TypeGuard<T, S1 | S2 | S3 | S4>;
+/**
+ * Combines multiple type guards with AND logic.
+ * Returns true only if all guards match.
+ *
+ * @example
+ * const isNonEmptyString = allOf(
+ *   isString,
+ *   (s): s is string => s.length > 0
+ * )
+ */
+declare function allOf<T, S1 extends T>(guard1: TypeGuard<T, S1>): TypeGuard<T, S1>;
+declare function allOf<T, S1 extends T, S2 extends S1>(guard1: TypeGuard<T, S1>, guard2: TypeGuard<S1, S2>): TypeGuard<T, S2>;
+declare function allOf<T, S1 extends T, S2 extends S1, S3 extends S2>(guard1: TypeGuard<T, S1>, guard2: TypeGuard<S1, S2>, guard3: TypeGuard<S2, S3>): TypeGuard<T, S3>;
+/**
+ * Negates a type guard.
+ *
+ * @example
+ * const isNotNull = not(isNull)
+ * const items = array.filter(isNotNull)
+ */
+declare function not<T, S extends T>(guard: TypeGuard<T, S>): TypeGuard<T, Exclude<T, S>>;
+/**
+ * Creates a type guard for array elements.
+ *
+ * @example
+ * const isStringArray = arrayOf(isString)
+ *
+ * if (isStringArray(value)) {
+ *   // value is string[]
+ * }
+ */
+declare function arrayOf<T, S extends T>(guard: TypeGuard<T, S>): TypeGuard<unknown, S[]>;
+/**
+ * Creates a type guard for objects with specific shape.
+ *
+ * @example
+ * const isUser = objectOf({
+ *   id: isNumber,
+ *   name: isString,
+ *   email: isString
+ * })
+ *
+ * if (isUser(data)) {
+ *   // data is { id: number; name: string; email: string }
+ * }
+ */
+declare function objectOf<T extends Record<string, TypeGuard<unknown, unknown>>>(shape: T): TypeGuard<unknown, {
+    [K in keyof T]: T[K] extends TypeGuard<unknown, infer S> ? S : never;
+}>;
+/**
+ * Creates a type guard for literal values.
+ *
+ * @example
+ * const isAdmin = literal('admin')
+ * const isStatus = oneOf(literal('pending'), literal('done'), literal('error'))
+ */
+declare function literal<T extends string | number | boolean>(expected: T): TypeGuard<unknown, T>;
+/**
+ * Creates a type guard for optional properties.
+ *
+ * @example
+ * const isOptionalString = optional(isString)
+ * // Matches string | undefined
+ */
+declare function optional<T, S extends T>(guard: TypeGuard<T, S>): TypeGuard<T | undefined, S | undefined>;
+/**
+ * Creates a type guard for nullable properties.
+ *
+ * @example
+ * const isNullableString = nullable(isString)
+ * // Matches string | null
+ */
+declare function nullable<T, S extends T>(guard: TypeGuard<T, S>): TypeGuard<T | null, S | null>;
+
+export { type Defined, type Falsy, type GuardedType, type Refinement, type Truthy, type TypeGuard, allOf, arrayOf, assertCondition, assertDefined, assertNotNull, assertType, chainNullable, createAssertion, createDiscriminantGuard, excludeNull, excludeNullish, excludeUndefined, exhaustiveCheck, filterBy, filterByGuard, filterByRefinement, filterDefined, filterDefinedFn, filterTruthy, filterTruthyFn, literal, mapNullable, narrowUnion, not, nullable, objectOf, oneOf, optional, partitionByGuard, refine, switchUnion, withDefault, withDefaultLazy };