@nicolastoulemont/std 0.5.1 → 0.7.0

package/dist/index-CUZn-ohG.d.mts

@@ -0,0 +1,490 @@
+//#region src/order/order.types.d.ts
+/**
+ * Ordering result of comparing two values.
+ *
+ * - `-1`: first value is less than second
+ * - `0`: values are equal
+ * - `1`: first value is greater than second
+ */
+type Ordering$1 = -1 | 0 | 1;
+/**
+ * Total ordering function for values of type `A`.
+ *
+ * An order must be consistent and return one of `-1 | 0 | 1`.
+ */
+type Order$1<in A> = (self: A, that: A) => Ordering$1;
+/**
+ * Inclusive bounds used by `clamp` and `between`.
+ */
+type OrderBounds<A> = {
+  readonly minimum: A;
+  readonly maximum: A;
+};
+declare namespace order_d_exports {
+  export { Order, Ordering, alwaysEqual, array, between, bigint, boolean, by, clamp, date, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, make, max, merge, min, number, reverse, sort, sortBy, sortWith, string, struct, tuple };
+}
+/**
+ * Re-exported `Order` type.
+ *
+ * @example
+ * ```ts
+ * import type { Order } from "@nicolastoulemont/std"
+ *
+ * type Example = Order.Order<unknown>
+ * ```
+ *
+ * @category Re-exports
+ */
+type Order<A> = Order$1<A>;
+/**
+ * Re-exported `Ordering` type.
+ *
+ * @example
+ * ```ts
+ * import type { Order } from "@nicolastoulemont/std"
+ *
+ * type Example = Order.Ordering
+ * ```
+ *
+ * @category Re-exports
+ */
+type Ordering = Ordering$1;
+/**
+ * Create an `Order` from a comparison function.
+ *
+ * The created order short-circuits identical references (`===`) to `0`.
+ *
+ * @param compare - Comparison function returning `-1 | 0 | 1`
+ * @returns An order function
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const byLength = Order.make<string>((self, that) =>
+ *   self.length < that.length ? -1 : self.length > that.length ? 1 : 0,
+ * )
+ * const result = byLength("a", "bbb")
+ * // => -1
+ * ```
+ *
+ * @category Constructors
+ */
+declare function make<A>(compare: (self: A, that: A) => Ordering): Order$1<A>;
+/**
+ * `Order` instance for strings (lexicographic, case-sensitive).
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const result = Order.string("a", "b")
+ * // => -1
+ * ```
+ *
+ * @category Instances
+ */
+declare const string: Order$1<string>;
+/**
+ * `Order` instance for numbers.
+ *
+ * - `NaN` equals `NaN`
+ * - `NaN` is less than any non-`NaN`
+ * - `0` equals `-0`
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const result = Order.number(1, 2)
+ * // => -1
+ * ```
+ *
+ * @category Instances
+ */
+declare const number: Order$1<number>;
+/**
+ * `Order` instance for booleans where `false < true`.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const result = Order.boolean(false, true)
+ * // => -1
+ * ```
+ *
+ * @category Instances
+ */
+declare const boolean: Order$1<boolean>;
+/**
+ * `Order` instance for bigints.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const result = Order.bigint(1n, 2n)
+ * // => -1
+ * ```
+ *
+ * @category Instances
+ */
+declare const bigint: Order$1<bigint>;
+/**
+ * `Order` instance for dates based on `getTime()`.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const result = Order.date(new Date("2024-01-01"), new Date("2024-01-02"))
+ * // => -1
+ * ```
+ *
+ * @category Instances
+ */
+declare const date: Order$1<Date>;
+/**
+ * Create an order that treats all values as equal.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const compare = Order.alwaysEqual<number>()
+ * const result = compare(1, 2)
+ * // => 0
+ * ```
+ *
+ * @category Constructors
+ */
+declare function alwaysEqual<A>(): Order$1<A>;
+/**
+ * Reverse an existing order.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const desc = Order.reverse(Order.number)
+ * const result = desc(1, 2)
+ * // => 1
+ * ```
+ *
+ * @category Combinators
+ */
+declare function reverse<A>(order: Order$1<A>): Order$1<A>;
+/**
+ * Map inputs before comparison.
+ *
+ * Supports data-first and data-last styles:
+ * - `by(order, project)`
+ * - `pipe(order, by(project))`
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * type User = { age: number }
+ * const dataFirst = Order.by(Order.number, (user: User) => user.age)
+ * const compareFirst = dataFirst({ age: 1 }, { age: 2 })
+ * // => -1
+ *
+ * const dataLast = Order.by((user: User) => user.age)(Order.number)
+ * const compareLast = dataLast({ age: 1 }, { age: 2 })
+ * // => -1
+ * ```
+ *
+ * @category Combinators
+ */
+declare const by: {
+  <B, A>(project: (value: B) => A): (order: Order$1<A>) => Order$1<B>;
+  <A, B>(order: Order$1<A>, project: (value: B) => A): Order$1<B>;
+};
+/**
+ * Merge orders lexicographically.
+ *
+ * Supports three forms:
+ * - `merge(self, that)`
+ * - `merge(that)(self)`
+ * - `merge([order1, order2, ...])`
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * type User = { first: string; last: string }
+ * const byLast = Order.by(Order.string, (user: User) => user.last)
+ * const byFirst = Order.by(Order.string, (user: User) => user.first)
+ * const compare = Order.merge([byLast, byFirst])({ first: "Ada", last: "Lovelace" }, { first: "Alan", last: "Turing" })
+ * // => -1
+ * ```
+ *
+ * @category Combining
+ */
+declare const merge: {
+  <A>(that: Order$1<A>): (self: Order$1<A>) => Order$1<A>;
+  <A>(self: Order$1<A>, that: Order$1<A>): Order$1<A>;
+  <A>(orders: Iterable<Order$1<A>>): Order$1<A>;
+};
+/**
+ * Create an order for tuples, compared left-to-right.
+ */
+type TupleOrders<Elements extends ReadonlyArray<unknown>> = { readonly [K in keyof Elements]: Order$1<Elements[K]> };
+/**
+ * tuple utility.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const compare = Order.tuple([Order.string, Order.number] as const)(["a", 1], ["a", 2])
+ * // => -1
+ * ```
+ *
+ * @category Constructors
+ */
+declare function tuple<const Elements extends ReadonlyArray<unknown>>(orders: TupleOrders<Elements>): Order$1<Elements>;
+/**
+ * Create an order for arrays.
+ *
+ * Arrays are compared element-by-element, then by length when all compared
+ * elements are equal.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const compare = Order.array(Order.number)([1, 2], [1, 3])
+ * // => -1
+ * ```
+ *
+ * @category Constructors
+ */
+declare function array<A>(order: Order$1<A>): Order$1<readonly A[]>;
+/**
+ * Create an order for objects by key order in `fields`.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const compare = Order.struct<{ id: number; name: string }>({
+ *   id: Order.number,
+ *   name: Order.string,
+ * })({ id: 1, name: "a" }, { id: 1, name: "b" })
+ * // => -1
+ * ```
+ *
+ * @category Constructors
+ */
+declare function struct<const R extends Record<string, unknown>>(fields: { readonly [K in keyof R]: Order$1<R[K]> }): Order$1<R>;
+/**
+ * Test strict less-than using an order.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const result = Order.lessThan(Order.number)(1, 2)
+ * // => true
+ * ```
+ *
+ * @category Predicates
+ */
+declare const lessThan: <A>(order: Order$1<A>) => {
+  (that: A): (self: A) => boolean;
+  (self: A, that: A): boolean;
+};
+/**
+ * Test less-than-or-equal using an order.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const result = Order.lessThanOrEqual(Order.number)(2, 2)
+ * // => true
+ * ```
+ *
+ * @category Predicates
+ */
+declare const lessThanOrEqual: <A>(order: Order$1<A>) => {
+  (that: A): (self: A) => boolean;
+  (self: A, that: A): boolean;
+};
+/**
+ * Test strict greater-than using an order.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const result = Order.greaterThan(Order.number)(3, 2)
+ * // => true
+ * ```
+ *
+ * @category Predicates
+ */
+declare const greaterThan: <A>(order: Order$1<A>) => {
+  (that: A): (self: A) => boolean;
+  (self: A, that: A): boolean;
+};
+/**
+ * Test greater-than-or-equal using an order.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const result = Order.greaterThanOrEqual(Order.number)(2, 2)
+ * // => true
+ * ```
+ *
+ * @category Predicates
+ */
+declare const greaterThanOrEqual: <A>(order: Order$1<A>) => {
+  (that: A): (self: A) => boolean;
+  (self: A, that: A): boolean;
+};
+/**
+ * Get the minimum of two values.
+ *
+ * If equal, returns the first argument.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const value = Order.min(Order.number)(3, 5)
+ * // => 3
+ * ```
+ *
+ * @category Combinators
+ */
+declare const min: <A>(order: Order$1<A>) => {
+  (that: A): (self: A) => A;
+  (self: A, that: A): A;
+};
+/**
+ * Get the maximum of two values.
+ *
+ * If equal, returns the first argument.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const value = Order.max(Order.number)(3, 5)
+ * // => 5
+ * ```
+ *
+ * @category Combinators
+ */
+declare const max: <A>(order: Order$1<A>) => {
+  (that: A): (self: A) => A;
+  (self: A, that: A): A;
+};
+/**
+ * Clamp a value to inclusive bounds.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const value = Order.clamp(Order.number)(7, { minimum: 0, maximum: 5 })
+ * // => 5
+ * ```
+ *
+ * @category Combinators
+ */
+declare const clamp: <A>(order: Order$1<A>) => {
+  (bounds: OrderBounds<A>): (self: A) => A;
+  (self: A, bounds: OrderBounds<A>): A;
+};
+/**
+ * Check whether a value is within inclusive bounds.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const isBetween = Order.between(Order.number)(3, { minimum: 0, maximum: 5 })
+ * // => true
+ * ```
+ *
+ * @category Predicates
+ */
+declare const between: <A>(order: Order$1<A>) => {
+  (bounds: OrderBounds<A>): (self: A) => boolean;
+  (self: A, bounds: OrderBounds<A>): boolean;
+};
+/**
+ * Sort an iterable by an order, returning a new array.
+ *
+ * Supports data-first and data-last styles.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const values = [3, 1, 2]
+ * const dataFirst = Order.sort(values, Order.number)
+ * // => [1, 2, 3]
+ *
+ * const dataLast = Order.sort(Order.number)(values)
+ * // => [1, 2, 3]
+ * ```
+ *
+ * @category Utilities
+ */
+declare const sort: {
+  <B>(order: Order$1<B>): <A extends B>(input: Iterable<A>) => A[];
+  <A extends B, B>(input: Iterable<A>, order: Order$1<B>): A[];
+};
+/**
+ * Sort an iterable by a projected value.
+ *
+ * Supports data-first and data-last styles.
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const users = [{ age: 2 }, { age: 1 }]
+ * const dataFirst = Order.sortWith(users, (user) => user.age, Order.number)
+ * // => [{ age: 1 }, { age: 2 }]
+ *
+ * const dataLast = Order.sortWith((user: { age: number }) => user.age, Order.number)(users)
+ * // => [{ age: 1 }, { age: 2 }]
+ * ```
+ *
+ * @category Utilities
+ */
+declare const sortWith: {
+  <A, B>(project: (value: A) => B, order: Order$1<B>): (input: Iterable<A>) => A[];
+  <A, B>(input: Iterable<A>, project: (value: A) => B, order: Order$1<B>): A[];
+};
+/**
+ * Sort an iterable by multiple orders, in sequence.
+ *
+ * - first order has highest priority
+ * - ties are broken by subsequent orders
+ * - no orders returns a shallow copy preserving iteration order
+ *
+ * @example
+ * ```ts
+ * import { Order } from "@nicolastoulemont/std"
+ *
+ * const users = [{ age: 2, name: "b" }, { age: 1, name: "a" }]
+ * const sorted = Order.sortBy(Order.by(Order.number, (user: { age: number; name: string }) => user.age))(users)
+ * // => [{ age: 1, name: "a" }, { age: 2, name: "b" }]
+ * ```
+ *
+ * @category Utilities
+ */
+declare const sortBy: <A>(...orders: readonly Order$1<A>[]) => (input: Iterable<A>) => A[];
+//#endregion
+export { order_d_exports as t };
+//# sourceMappingURL=index-CUZn-ohG.d.mts.map

package/dist/index-CUZn-ohG.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-CUZn-ohG.d.mts","names":[],"sources":["../src/order/order.types.ts","../src/order/order.ts"],"sourcesContent":[],"mappings":";;;;AAOA;AAOA;;;AAAgD,KAPpC,UAAA,GAOoC,CAAA,CAAA,GAAA,CAAA,GAAA,CAAA;;AAKhD;;;;KALY,uBAAqB,SAAS,MAAM;;;;KAKpC;oBACQ;oBACA;;;;;;;AAdpB;AAOA;;;;;AAKA;;;;KCwBY,WAAW,QAAU;;;;;;;;;;;;;KAcrB,QAAA,GAAW;;;;;;;;;;;;;;;AAdvB;AAcA;AAuBA;;;;;AAAkE,iBAAlD,IAAkD,CAAA,CAAA,CAAA,CAAA,OAAA,EAAA,CAAA,IAAA,EAA1B,CAA0B,EAAA,IAAA,EAAjB,CAAiB,EAAA,GAAX,QAAW,CAAA,EAAA,OAAA,CAAU,CAAV,CAAA;;AAiBlE;AAmBA;AAoBA;AAeA;AAeA;AAgBA;AAkBA;;;;;;AA2Ba,cAlIA,MAyIZ,EAzIoB,OAyIpB,CAAA,MAAA,CAAA;;;;;;;;;;;;;;AAiED;;;;AACkC,cAxLrB,MAwLqB,EAxLb,OAwLa,CAAA,MAAA,CAAA;;;;;;;;;;;;;;AAEc,cAtKnC,OAsKmC,EAtK1B,OAsK0B,CAAA,OAAA,CAAA;AAC/B;;;;;;;AAsBjB;;;;;;AAEY,cAhLC,MAgLD,EAhLS,OAgLT,CAAA,MAAA,CAAA;AA2BZ;;;;;;AA2BA;;;;;;;AAEI,cAzNS,IAyNT,EAzNe,OAyNf,CAzNyB,IAyNzB,CAAA;;AAyBJ;;;;;;;;AAoBA;;;;;AAIS,iBA1PO,WA0PP,CAAA,CAAA,CAAA,CAAA,CAAA,EA1PyB,OA0PzB,CA1PmC,CA0PnC,CAAA;;;AAgBT;;;;;;;;AAoBA;;;;AAGoB,iBA/QJ,OA+QI,CAAA,CAAA,CAAA,CAAA,KAAA,EA/Qc,OA+Qd,CA/QwB,CA+QxB,CAAA,CAAA,EA/Q6B,OA+Q7B,CA/QuC,CA+QvC,CAAA;;;;AAmBpB;;;;;;;;;;AAsBA;;;;;;;;;;AAoBa,cAjTA,EAsTqG,EAAA;EAJ/F,CAAA,CAAA,EAAA,CAAA,CAAA,CAAA,OAAA,EAAA,CAAA,KAAA,EAjTO,CAiTP,EAAA,GAjTa,CAiTb,CAAA,EAAA,CAAA,KAAA,EAjTyB,OAiTzB,CAjTmC,CAiTnC,CAAA,EAAA,GAjT0C,OAiT1C,CAjToD,CAiTpD,CAAA;EAAV,CAAA,CAAA,EAAA,CAAA,CAAA,CAAA,KAAA,EAhTO,OAgTP,CAhTiB,CAgTjB,CAAA,EAAA,OAAA,EAAA,CAAA,KAAA,EAhTsC,CAgTtC,EAAA,GAhT4C,CAgT5C,CAAA,EAhTgD,OAgThD,CAhT0D,CAgT1D,CAAA;CAEc;;;;;;;;;AAiBvB;;;;;;;;;;AA+BA;;;AACuC,cA7R1B,KA6R0B,EAAA;EAAmB,CAAA,CAAA,CAAA,CAAA,IAAA,EA5R9C,OA4R8C,CA5RpC,CA4RoC,CAAA,CAAA,EAAA,CAAA,IAAA,EA5RxB,OA4RwB,CA5Rd,CA4Rc,CAAA,EAAA,GA5RP,OA4RO,CA5RG,CA4RH,CAAA;EAAT,CAAA,CAAA,CAAA,CAAA,IAAA,EA3RrC,OA2RqC,CA3R3B,CA2R2B,CAAA,EAAA,IAAA,EA3RjB,OA2RiB,CA3RP,CA2RO,CAAA,CAAA,EA3RF,OA2RE,CA3RQ,CA2RR,CAAA;EAAgB,CAAA,CAAA,CAAA,CAAA,MAAA,EA1RnD,QA0RmD,CA1R1C,OA0R0C,CA1RhC,CA0RgC,CAAA,CAAA,CAAA,EA1R1B,OA0R0B,CA1RhB,CA0RgB,CAAA;CACpD;;;;KArRR,WAqRyC,CAAA,iBArRZ,aAqRY,CAAA,OAAA,CAAA,CAAA,GAAA,iBAAe,MApRtC,QAoRsC,GApR3B,OAoR2B,CApRjB,QAoRiB,CApRR,CAoRQ,CAAA,CAAA,EAAC;AA0B9D;;;;;;;;;;;;;AAE8D,iBAhS9C,KAgS8C,CAAA,uBAhSjB,aAgSiB,CAAA,OAAA,CAAA,CAAA,CAAA,MAAA,EA/RpD,WA+RoD,CA/RxC,QA+RwC,CAAA,CAAA,EA9R3D,OA8R2D,CA9RjD,QA8RiD,CAAA;;;AAyB9D;;;;;;;;;;;;;;iBA5RgB,gBAAgB,QAAU,KAAK,iBAAmB;;;;;;;;;;;;;;;;;iBA2BlD,uBAAuB,wDAChB,IAAI,QAAU,EAAE,QACnC,QAAU;;;;;;;;;;;;;;cAyBD,qBACJ,QAAU;SAEV,WAAW;SACX,SAAS;;;;;;;;;;;;;;;cAgBL,4BACJ,QAAU;SAEV,WAAW;SACX,SAAS;;;;;;;;;;;;;;;cAgBL,wBACJ,QAAU;SAEV,WAAW;SACX,SAAS;;;;;;;;;;;;;;;cAgBL,+BACJ,QAAU;SAEV,WAAW;SACX,SAAS;;;;;;;;;;;;;;;;;cAkBL,gBACJ,QAAU;SAEV,WAAW,MAAM;SACjB,SAAS,IAAI;;;;;;;;;;;;;;;;;cAkBT,gBACJ,QAAU;SAEV,WAAW,MAAM;SACjB,SAAS,IAAI;;;;;;;;;;;;;;;cAgBT,kBACJ,QAAU;WAER,YAAY,YAAY,MAAM;SAChC,WAAW,YAAY,KAAK;;;;;;;;;;;;;;;cAgBxB,oBACJ,QAAU;WAER,YAAY,YAAY;SAC1B,WAAW,YAAY;;;;;;;;;;;;;;;;;;;;;cA2BnB;aACA,QAAU,gBAAgB,UAAU,SAAS,OAAO;aACpD,aAAa,SAAS,WAAW,QAAU,KAAK;;;;;;;;;;;;;;;;;;;;;cA0BhD;0BACa,MAAM,UAAU,QAAU,aAAa,SAAS,OAAO;gBACjE,SAAS,qBAAqB,MAAM,UAAU,QAAU,KAAK;;;;;;;;;;;;;;;;;;;;cAyBhE,gCAAiC,QAAU,iBAErC,SAAS,OAAK"}