@nicolastoulemont/std 0.3.0 → 0.5.0

package/dist/index-78LWwTds.d.mts

@@ -0,0 +1,288 @@
+//#region src/predicate/predicate.types.d.ts
+/**
+ * A predicate function that tests a value and returns a boolean.
+ *
+ * @template T - The type of value being tested
+ */
+type Predicate$1<in T> = (value: T) => boolean;
+/**
+ * A refinement predicate that narrows type T to subtype U.
+ * This is a type guard - when it returns true, TypeScript knows
+ * the value is of the narrower type U.
+ *
+ * @template T - The base type
+ * @template U - The narrower type (must extend T)
+ *
+ * @example
+ * ```ts
+ * // Built-in refinement
+ * const isString: Refinement<unknown, string> = (v): v is string =>
+ *   typeof v === "string"
+ *
+ * // Usage with filter
+ * const mixed: (string | number)[] = ["a", 1, "b", 2]
+ * const strings: string[] = mixed.filter(isString)
+ * ```
+ */
+type Refinement<in T, out U extends T> = (value: T) => value is U;
+//#endregion
+//#region src/predicate/predicate.d.ts
+/**
+ * Negate a predicate.
+ * Returns true when the original predicate returns false, and vice versa.
+ *
+ * @template T - The type being tested
+ * @param predicate - The predicate to negate
+ * @returns A new predicate that returns the opposite boolean
+ *
+ * @example
+ * ```ts
+ * const isEven = (n: number) => n % 2 === 0
+ * const isOdd = Predicate.not(isEven)
+ *
+ * isOdd(3) // true
+ * isOdd(4) // false
+ *
+ * // Works in filter
+ * [1, 2, 3, 4].filter(Predicate.not(isEven)) // [1, 3]
+ * ```
+ */
+declare const not: <T>(predicate: Predicate$1<T>) => Predicate$1<T>;
+/**
+ * Combine predicates with logical AND.
+ * Returns true only when ALL predicates return true.
+ * Short-circuits on first false (lazy evaluation).
+ *
+ * @template T - The type being tested
+ * @param predicates - The predicates to combine
+ * @returns A new predicate that returns true if all predicates pass
+ *
+ * @example
+ * ```ts
+ * const isPositive = (n: number) => n > 0
+ * const isEven = (n: number) => n % 2 === 0
+ * const isLessThan100 = (n: number) => n < 100
+ *
+ * const isValidNumber = Predicate.and(isPositive, isEven, isLessThan100)
+ *
+ * isValidNumber(42) // true
+ * isValidNumber(-2) // false (not positive)
+ * isValidNumber(101) // false (not less than 100)
+ * ```
+ */
+declare const and: <T>(...predicates: readonly Predicate$1<T>[]) => Predicate$1<T>;
+/**
+ * Combine predicates with logical OR.
+ * Returns true when ANY predicate returns true.
+ * Short-circuits on first true (lazy evaluation).
+ *
+ * @template T - The type being tested
+ * @param predicates - The predicates to combine
+ * @returns A new predicate that returns true if any predicate passes
+ *
+ * @example
+ * ```ts
+ * const isZero = (n: number) => n === 0
+ * const isNegative = (n: number) => n < 0
+ *
+ * const isNotPositive = Predicate.or(isZero, isNegative)
+ *
+ * isNotPositive(0) // true
+ * isNotPositive(-5) // true
+ * isNotPositive(5) // false
+ * ```
+ */
+declare const or: <T>(...predicates: readonly Predicate$1<T>[]) => Predicate$1<T>;
+/**
+ * Create a predicate that tests if ALL elements in an array match.
+ * Returns true for empty arrays (vacuous truth).
+ *
+ * @template T - The element type
+ * @param predicate - The predicate to test each element
+ * @returns A predicate that takes an array and returns true if all match
+ *
+ * @example
+ * ```ts
+ * const isPositive = (n: number) => n > 0
+ * const allPositive = Predicate.all(isPositive)
+ *
+ * allPositive([1, 2, 3]) // true
+ * allPositive([1, -2, 3]) // false
+ * allPositive([]) // true (vacuous truth)
+ *
+ * // Useful for validation
+ * const areAllAdults = Predicate.all((u: User) => u.age >= 18)
+ * ```
+ */
+declare const all: <T>(predicate: Predicate$1<T>) => Predicate$1<readonly T[]>;
+/**
+ * Create a predicate that tests if ANY element in an array matches.
+ * Returns false for empty arrays.
+ *
+ * @template T - The element type
+ * @param predicate - The predicate to test each element
+ * @returns A predicate that takes an array and returns true if any match
+ *
+ * @example
+ * ```ts
+ * const isNegative = (n: number) => n < 0
+ * const hasNegative = Predicate.some(isNegative)
+ *
+ * hasNegative([1, -2, 3]) // true
+ * hasNegative([1, 2, 3]) // false
+ * hasNegative([]) // false
+ * ```
+ */
+declare const some: <T>(predicate: Predicate$1<T>) => Predicate$1<readonly T[]>;
+/**
+ * Create a predicate that tests if NO elements in an array match.
+ * Returns true for empty arrays (vacuous truth).
+ * Equivalent to `not(some(predicate))`.
+ *
+ * @template T - The element type
+ * @param predicate - The predicate that should NOT match any element
+ * @returns A predicate that takes an array and returns true if none match
+ *
+ * @example
+ * ```ts
+ * const isNegative = (n: number) => n < 0
+ * const noNegatives = Predicate.none(isNegative)
+ *
+ * noNegatives([1, 2, 3]) // true
+ * noNegatives([1, -2, 3]) // false
+ * noNegatives([]) // true (vacuous truth)
+ * ```
+ */
+declare const none: <T>(predicate: Predicate$1<T>) => Predicate$1<readonly T[]>;
+/**
+ * Combine refinements with logical AND, preserving type narrowing.
+ * Use this instead of `and` when you need to preserve type guard behavior.
+ *
+ * @template T - The base type
+ * @template U - The narrowed type (must extend T)
+ * @param refinements - The refinements to combine
+ * @returns A refinement that narrows to U if all refinements pass
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; age: number; verified?: boolean }
+ * type Adult = User & { age: number } // age >= 18
+ * type VerifiedAdult = Adult & { verified: true }
+ *
+ * const isAdult = (u: User): u is Adult => u.age >= 18
+ * const isVerified = (u: User): u is User & { verified: true } => u.verified === true
+ *
+ * // Combined refinement preserves type narrowing
+ * const isVerifiedAdult = Predicate.andRefinement<User, VerifiedAdult>(isAdult, isVerified)
+ *
+ * if (isVerifiedAdult(user)) {
+ *   user.verified // TypeScript knows this is true
+ * }
+ * ```
+ */
+declare const andRefinement: <T, U extends T>(...refinements: readonly Refinement<T, U>[]) => Refinement<T, U>;
+/**
+ * Combine refinements with logical OR, preserving type narrowing.
+ * Use this instead of `or` when you need to preserve type guard behavior.
+ *
+ * @template T - The base type
+ * @template U - The narrowed type (must extend T)
+ * @param refinements - The refinements to combine
+ * @returns A refinement that narrows to U if any refinement passes
+ *
+ * @example
+ * ```ts
+ * const isString = (v: unknown): v is string => typeof v === "string"
+ * const isNumber = (v: unknown): v is number => typeof v === "number"
+ *
+ * const isStringOrNumber = Predicate.orRefinement<unknown, string | number>(isString, isNumber)
+ *
+ * if (isStringOrNumber(value)) {
+ *   // value is string | number
+ * }
+ * ```
+ */
+declare const orRefinement: <T, U extends T>(...refinements: readonly Refinement<T, U>[]) => Refinement<T, U>;
+/**
+ * Create a predicate from a constant boolean value.
+ * Useful for testing or as a placeholder.
+ *
+ * @template T - The type (can be anything)
+ * @param value - The constant boolean to return
+ * @returns A predicate that always returns the given value
+ *
+ * @example
+ * ```ts
+ * const alwaysTrue = Predicate.constant(true)
+ * const alwaysFalse = Predicate.constant(false)
+ *
+ * alwaysTrue("anything") // true
+ * alwaysFalse(42) // false
+ * ```
+ */
+declare const constant: <T>(value: boolean) => Predicate$1<T>;
+/**
+ * Create a predicate that checks strict equality.
+ *
+ * @template T - The type being compared
+ * @param expected - The value to compare against
+ * @returns A predicate that returns true if value === expected
+ *
+ * @example
+ * ```ts
+ * const isZero = Predicate.equals(0)
+ * const isHello = Predicate.equals("hello")
+ *
+ * isZero(0) // true
+ * isZero(1) // false
+ *
+ * // Works with references too
+ * const obj = { a: 1 }
+ * const isObj = Predicate.equals(obj)
+ * isObj(obj) // true
+ * isObj({ a: 1 }) // false (different reference)
+ * ```
+ */
+declare const equals: <T>(expected: T) => Predicate$1<T>;
+/**
+ * Predicate namespace containing composable boolean functions.
+ *
+ * Predicates are functions that test values and return booleans.
+ * This namespace provides combinators to build complex predicates
+ * from simple ones, with support for type guards (refinements).
+ *
+ * @example
+ * ```ts
+ * import { Predicate, pipe } from "@repo/std"
+ *
+ * // Basic predicates
+ * const isPositive = (n: number) => n > 0
+ * const isEven = (n: number) => n % 2 === 0
+ *
+ * // Combine with and/or
+ * const isPositiveEven = Predicate.and(isPositive, isEven)
+ * const isZeroOrNegative = Predicate.or(Predicate.equals(0), Predicate.not(isPositive))
+ *
+ * // Array predicates
+ * const allPositive = Predicate.all(isPositive)
+ * const hasNegative = Predicate.some(Predicate.not(isPositive))
+ *
+ * // Use with filter
+ * [1, 2, 3, 4, 5].filter(isPositiveEven) // [2, 4]
+ * ```
+ */
+declare const Predicate: {
+  readonly not: <T>(predicate: Predicate$1<T>) => Predicate$1<T>;
+  readonly and: <T>(...predicates: readonly Predicate$1<T>[]) => Predicate$1<T>;
+  readonly or: <T>(...predicates: readonly Predicate$1<T>[]) => Predicate$1<T>;
+  readonly all: <T>(predicate: Predicate$1<T>) => Predicate$1<readonly T[]>;
+  readonly some: <T>(predicate: Predicate$1<T>) => Predicate$1<readonly T[]>;
+  readonly none: <T>(predicate: Predicate$1<T>) => Predicate$1<readonly T[]>;
+  readonly andRefinement: <T, U extends T>(...refinements: readonly Refinement<T, U>[]) => Refinement<T, U>;
+  readonly orRefinement: <T, U extends T>(...refinements: readonly Refinement<T, U>[]) => Refinement<T, U>;
+  readonly constant: <T>(value: boolean) => Predicate$1<T>;
+  readonly equals: <T>(expected: T) => Predicate$1<T>;
+};
+//#endregion
+export { constant as a, not as c, some as d, Predicate$1 as f, andRefinement as i, or as l, all as n, equals as o, Refinement as p, and as r, none as s, Predicate as t, orRefinement as u };
+//# sourceMappingURL=index-78LWwTds.d.mts.map

package/dist/index-78LWwTds.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-78LWwTds.d.mts","names":[],"sources":["../src/predicate/predicate.types.ts","../src/predicate/predicate.ts"],"sourcesContent":[],"mappings":";;AAKA;AAqBA;;;AAAuE,KArB3D,WAqB2D,CAAA,IAAA,CAAA,GAAA,CAAA,KAAA,EArBjC,CAqBiC,EAAA,GAAA,OAAA;;;;;ACJvE;;;;;;AA0BA;;;;;;AA8BA;;;AAAiF,KDpDrE,UCoDqE,CAAA,IAAA,EAAA,cDpDtC,CCoDsC,CAAA,GAAA,CAAA,KAAA,EDpDzB,CCoDyB,EAAA,GAAA,KAAA,IDpDV,CCoDU;;;ADzEjF;AAqBA;;;;;;;;ACJA;;;;;;AA0BA;;;;;AAAiF,cA1BpE,GA0BoE,EAAA,CAAA,CAAA,CAAA,CAAA,SAAA,EA1B/C,WA0B+C,CA1BjC,CA0BiC,CAAA,EAAA,GA1B5B,WA0B4B,CA1Bd,CA0Bc,CAAA;AA8BjF;;;;;;AA8BA;;;;;;AAsBA;;;;;;AAuBA;;;;AAAsD,cAzGzC,GAyGyC,EAAA,CAAA,CAAA,CAAA,CAAA,GAAA,UAAA,EAAA,SAzGP,WAyGO,CAzGO,CAyGP,CAAA,EAAA,EAAA,GAzGc,WAyGd,CAzG4B,CAyG5B,CAAA;;AA8BtD;;;;;;;;;AA8BA;;;;;;;;;AA0BA;AA0BA;AAAoC,cA3LvB,EA2LuB,EAAA,CAAA,CAAA,CAAA,CAAA,GAAA,UAAA,EAAA,SA3LU,WA2LV,CA3LwB,CA2LxB,CAAA,EAAA,EAAA,GA3L+B,WA2L/B,CA3L6C,CA2L7C,CAAA;;;;AA+BpC;;;;;;;;;;;;;;;;;;AAtKmC,cAtBtB,GAsBsB,EAAA,CAAA,CAAA,CAAA,CAAA,SAAA,EAtBD,WAsBC,CAtBa,CAsBb,CAAA,EAAA,GAtBkB,WAsBlB,CAAA,SAtByC,CAsBzC,EAAA,CAAA;;;;;;;;;;;;;;;;;;;AAmFsE,cAnF5F,IAmF4F,EAAA,CAAA,CAAA,CAAA,CAAA,SAAA,EAnFtE,WAmFsE,CAnFxD,CAmFwD,CAAA,EAAA,GAnFnD,WAmFmD,CAAA,SAnF5B,CAmF4B,EAAA,CAAA;;;;;;;;;;;;;;;;;;;;cA5D5F,qBAAsB,YAAc,OAAK,qBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;cA8BhE,6BAA8B,4BAA4B,WAAW,GAAG,SAAO,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;cA8B7F,4BAA6B,4BAA4B,WAAW,GAAG,SAAO,WAAW,GAAG;;;;;;;;;;;;;;;;;;cA0B5F,iCAAgC,YAAc;;;;;;;;;;;;;;;;;;;;;;;cA0B9C,sBAAuB,MAAI,YAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+BzC;+BAlRqB,YAAc,OAAK,YAAc;4CA0BpB,YAAc,SAAO,YAAc;2CA8BpC,YAAc,SAAO,YAAc;+BA8B/C,YAAc,OAAK,qBAAuB;gCAsBzC,YAAc,OAAK,qBAAuB;gCAuB1C,YAAc,OAAK,qBAAuB;wCA8BlC,4BAA4B,WAAW,GAAG,SAAO,WAAW,GAAG;uCA8BhE,4BAA4B,WAAW,GAAG,SAAO,WAAW,GAAG;4CA0B5D,YAAc;iCA0BvB,MAAI,YAAc"}