tiinvo
Version:
A library of types and utilities for your TypeScript and JavaScript projects
634 lines (633 loc) • 18 kB
TypeScript
import type * as Functors from './Functors.js';
import type * as Fn from './Fn.js';
import type * as Option from './Option.js';
declare const guardsymbolKey: unique symbol;
declare const guardsymbolValue: unique symbol;
declare const valuessymbol: unique symbol;
/**
* Represents a `TypedMap<K, V>`.
*
* @example
*
* ```ts
* import { TypedMap, Num, Str } from 'tiinvo'
*
* const tm0 = TypedMap.make(Num, Str)
* const tm1 = TypedMap.make(Num, Str, [[10, "hello"], [20, "world"]])
* ```
*
* @template K the key type of the TypedMap
* @template V the value type of the TypedMap
* @since 4.0.0
*/
export type T<K, V> = {
readonly [guardsymbolKey]: Functors.Guardable<K>;
readonly [guardsymbolValue]: Functors.Guardable<V>;
readonly [valuessymbol]: Map<K, V>;
[Symbol.iterator](): Iterator<readonly [K, V]>;
};
/**
* Creates a new `TypedMap.T<K, V>`.
*
* @example
*
* ```ts
* import { Str, Num, TypedMap } from 'tiinvo'
*
* const m = new Map<string, number>([['hello', 100], ['world', 200]])
*
* TypedMap.make(Str, Num)
* TypedMap.make(Str, Num, m)
* TypedMap.make(Str.guard, Num)
* TypedMap.make(Str.guard, Num, m)
* TypedMap.make(Str, Num.guard)
* TypedMap.make(Str, Num.guard, m)
* TypedMap.make(Str.guard, Num.guard)
* TypedMap.make(Str.guard, Num.guard, m)
* ```
*
* @template K the key type
* @template V the value type
* @returns the `TypedMap.T<K, V>`
* @group Factories
* @since 4.0.0
*/
export declare function make<K, V>(kg: Functors.Guardable<K> | Functors.GuardableModule<K>, vg: Functors.Guardable<V> | Functors.GuardableModule<V>, entries?: Iterable<readonly [K, V]>): T<K, V>;
/**
* Checks if `x` is a `TypedMap.T<unknown, unknown>`
*
* @example
*
* ```ts
* import { TypedMap, Num, Str } from 'tiinvo'
*
* TypedMap.guard(10) // false
* TypedMap.guard({}) // false
* TypedMap.guard(TypedMap.make(Num, Str)) // true
* ```
*
* @param x the value to check
* @returns
* - `true` if `x` is a `TypedMap.T<unknown, unknown>`
* - `false` otherwise
* @group Guardables
* @since 4.0.0
*/
export declare const guard: (x: unknown) => x is T<unknown, unknown>;
/**
* Checks if `x` is of type `T<K, V>`
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* TypedMap.guardOf(Str, Num, 10) // false
* TypedMap.guardOf(Str, Num, TypedMap.make(Str, Num, [["hello", 10]])) // true
* TypedMap.guardOf(Num, Num, TypedMap.make(Str, Num, [["hello", 10]])) // false
* ```
*
* @returns
* - `true` if `x` is a `TypedMap.T<K, V>`
* - `false` otherwise
* @group Guardables
* @since 4.0.0
*/
export declare function guardOf<K, V>(kg: Functors.Guardable<K> | Functors.GuardableModule<K>, vg: Functors.Guardable<V> | Functors.GuardableModule<V>, x: unknown): x is T<K, V>;
/**
* Returns a unary function which checks if `x` is of type `T<K, V>`
*
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const guard0 = TypedMap.guardOf(Str, Num);
* const guard1 = TypedMap.guardOf(Str.guard, Num);
* const guard2 = TypedMap.guardOf(Str, Num.guard);
* const guard3 = TypedMap.guardOf(Str.guard, Num.guard);
* const m1 = TypedMap.make(Str, Num, [["hello", 10]]);
* const m2 = TypedMap.make(Num, Str, [[10, "hello"]]);
*
* guard0(10) // false
* guard0(m1) // true
* guard0(m2) // false
* guard1(10) // false
* guard1(m1) // true
* guard1(m2) // false
* guard2(10) // false
* guard2(m1) // true
* guard2(m2) // false
* guard3(10) // false
* guard3(m1) // true
* guard3(m2) // false
* ```
*
* @returns the unary function which returns
* - `true` if `x` is a `TypedMap.T<K, V>`
* - `false` otherwise
* @group Guardables
* @since 4.0.0
*/
export declare function guardOf<K, V>(kg: Functors.Guardable<K> | Functors.GuardableModule<K>, vg: Functors.Guardable<V> | Functors.GuardableModule<V>): (x: unknown) => x is T<K, V>;
/**
* Compares two `TypedMap`s with a key comparer and a value comparer
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const m0 = TypedMap.make(Str, Num, [["a", 1], ["b", 2]])
* const m1 = TypedMap.make(Str, Num, [["a", 1]])
* const m2 = TypedMap.make(Str, Num, [["a", 1], ["b", 2]])
* const m3 = TypedMap.make(Str, Num, [["b", 1], ["c", 2]])
*
* TypedMap.cmp(Str, Num, m0, m1) // 1
* TypedMap.cmp(Str, Num, m0, m2) // 0
* TypedMap.cmp(Str, Num, m0, m3) // -1
* ```
*
* @template K the key type
* @template V the value type
* @param kmod the key comparer
* @param vmod the value comparer
* @param a the first TypedMap
* @param b the second TypedMap
* @returns
* - -1 if `a` is less than `b`
* - 0 if `a` is equal to `b`
* - 1 if `a` is greater than `b`
* @group Comparables
* @since 4.0.0
*/
export declare function cmp<K, V>(kmod: Functors.Comparable<K> | Functors.ComparableModule<K>, vmod: Functors.Comparable<V> | Functors.ComparableModule<V>, a: T<K, V>, b: T<K, V>): Functors.ComparableResult;
/**
* Returns a unary function which compares two `TypedMap`s with a key comparer and a value comparer
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const cmp = TypedMap.cmp(Str, Num, TypedMap.make(Str, Num, [["a", 1], ["b", 2]]))
* const m1 = TypedMap.make(Str, Num, [["a", 1]])
* const m2 = TypedMap.make(Str, Num, [["a", 1], ["b", 2]])
* const m3 = TypedMap.make(Str, Num, [["b", 1], ["c", 2]])
*
* cmp(m1) // -1
* cmp(m2) // 0
* cmp(m3) // 1
* ```
*
* @template K the key type
* @template V the value type
* @param kmod the key comparer
* @param vmod the value comparer
* @param a the first TypedMap
* @returns the unary function which returns
* - -1 if `b` is less than `a`
* - 0 if `b` is equal to `a`
* - 1 if `b` is greater than `a`
* @group Comparables
* @since 4.0.0
*/
export declare function cmp<K, V>(kmod: Functors.Comparable<K> | Functors.ComparableModule<K>, vmod: Functors.Comparable<V> | Functors.ComparableModule<V>, a: T<K, V>): Fn.Unary<T<K, V>, Functors.ComparableResult>;
/**
* Returns a binary function which compares two `TypedMap`s with a key comparer and a value comparer
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const cmp = TypedMap.cmp(Str, Num)
* const m0 = TypedMap.make(Str, Num, [["a", 1], ["b", 2]]);
* const m1 = TypedMap.make(Str, Num, [["a", 1]])
* const m2 = TypedMap.make(Str, Num, [["a", 1], ["b", 2]])
* const m3 = TypedMap.make(Str, Num, [["b", 1], ["c", 2]])
*
* cmp(m0, m1) // 1
* cmp(m0, m2) // 0
* cmp(m0, m3) // -1
* ```
*
* @template K the key type
* @template V the value type
* @param kmod the key comparer
* @param vmod the value comparer
* @returns the binary function which returns
* - -1 if `a` is less than `b`
* - 0 if `a` is equal to `b`
* - 1 if `a` is greater than `b`
* @group Comparables
* @since 4.0.0
*/
export declare function cmp<K, V>(kmod: Functors.Comparable<K> | Functors.ComparableModule<K>, vmod: Functors.Comparable<V> | Functors.ComparableModule<V>): Fn.Binary<T<K, V>, T<K, V>, Functors.ComparableResult>;
/**
* Compares two `TypedMap`s with a key comparer and a value comparer
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const m0 = TypedMap.make(Str, Num, [["a", 1], ["b", 2]])
* const m1 = TypedMap.make(Str, Num, [["a", 1]])
* const m2 = TypedMap.make(Str, Num, [["a", 1], ["b", 2]])
* const m3 = TypedMap.make(Str, Num, [["b", 1], ["c", 2]])
*
* TypedMap.eq(Str, Num, m0, m1) // false
* TypedMap.eq(Str, Num, m0, m2) // true
* TypedMap.eq(Str, Num, m0, m3) // false
* ```
*
* @template K the key type
* @template V the value type
* @param kmod the key comparer
* @param vmod the value comparer
* @param a the first TypedMap
* @param b the second TypedMap
* @returns
* - `true` if `a` is equal to `b`
* - `false` otherwise
* @group Comparables
* @since 4.0.0
*/
export declare function eq<K, V>(kmod: Functors.Comparable<K> | Functors.ComparableModule<K>, vmod: Functors.Comparable<V> | Functors.ComparableModule<V>, a: T<K, V>, b: T<K, V>): boolean;
/**
* Returns a unary function which compares two `TypedMap`s with a key comparer and a value comparer
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const eq = TypedMap.eq(Str, Num, TypedMap.make(Str, Num, [["a", 1], ["b", 2]]))
* const m1 = TypedMap.make(Str, Num, [["a", 1]])
* const m2 = TypedMap.make(Str, Num, [["a", 1], ["b", 2]])
* const m3 = TypedMap.make(Str, Num, [["b", 1], ["c", 2]])
*
* eq(m1) // false
* eq(m2) // true
* eq(m3) // false
* ```
*
* @template K the key type
* @template V the value type
* @param kmod the key comparer
* @param vmod the value comparer
* @param a the first TypedMap
* @returns the unary function which returns
* - `true` if `a` is equal to `b`
* - `false` otherwise
* @group Comparables
* @since 4.0.0
*/
export declare function eq<K, V>(kmod: Functors.Comparable<K> | Functors.ComparableModule<K>, vmod: Functors.Comparable<V> | Functors.ComparableModule<V>, a: T<K, V>): Fn.Unary<T<K, V>, boolean>;
/**
* Returns a binary function which compares two `TypedMap`s with a key comparer and a value comparer
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const eq = TypedMap.eq(Str, Num)
* const m0 = TypedMap.make(Str, Num, [["a", 1], ["b", 2]]);
* const m1 = TypedMap.make(Str, Num, [["a", 1]])
* const m2 = TypedMap.make(Str, Num, [["a", 1], ["b", 2]])
* const m3 = TypedMap.make(Str, Num, [["b", 1], ["c", 2]])
*
* eq(m0, m1) // false
* eq(m0, m2) // true
* eq(m0, m3) // false
* ```
*
* @template K the key type
* @template V the value type
* @param kmod the key comparer
* @param vmod the value comparer
* @returns the binary function which returns
* - `true` if `a` is equal to `b`
* - `false` otherwise
* @group Comparables
* @since 4.0.0
*/
export declare function eq<K, V>(kmod: Functors.Comparable<K> | Functors.ComparableModule<K>, vmod: Functors.Comparable<V> | Functors.ComparableModule<V>): Fn.Binary<T<K, V>, T<K, V>, boolean>;
/**
* Returns an iterable of key, value pairs for every entry in the map.
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const m = TypedMap.make(Str, Num, [['a', 100], ['b', 200]])
*
* for (const [k, v] of TypedMap.entries(m)) {
* console.log(k, v)
* }
* // logs
* // 'a' 100
* // 'b' 200
* ```
*
* @template K the key type
* @template V the value type
* @param t the TypedMap
* @returns t entries
* @group Accessors
* @since 4.0.0
*/
export declare const entries: <K, V>(t: T<K, V>) => IterableIterator<[K, V]>;
/**
* Gets a value `Option.T<V>` stored with a key `K`
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const foo = TypedMap.make(Str, Num, [['a', 1], ['b', 2]])
*
* TypedMap.get("a") // 1
* TypedMap.get("b") // 2
* TypedMap.get("c") // null
* ```
*
* @template K the key type
* @template V the value type
* @param key the key
* @param t the TypedMap
* @returns
* - the value if any as `Option.Some<V>`
* - `Option.None` otherwise
* @group Accessors
* @since 4.0.0
*/
export declare function get<K, V>(key: K, t: T<K, V>): Option.T<V>;
/**
* Returns a unary function which gets a value `Option.T<V>` stored with a key `K`
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const foo = TypedMap.make(Str, Num, [['a', 1], ['b', 2]])
* const getA = TypedMap.get("a")
* const getB = TypedMap.get("b")
* const getC = TypedMap.get("c")
*
* getA(foo) // 1
* getB(foo) // 2
* getC(foo) // null
* ```
*
* @template K the key type
* @param key the key
* @group Accessors
* @since 4.0.0
*/
export declare function get<K>(key: K): <V>(t: T<K, V>) => Option.T<V>;
/**
* Checks if a TypedMap has a key `K`
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const m = TypedMap.make(Str, Num, [["hello", 100]])
*
* TypedMap.has("hello", m) // true
* TypedMap.has("world", m) // false
* ```
*
* @template K the key type
* @template V the value type
* @param key the key
* @param t the TypedMap
* @returns
* - `true` if the TypedMap has a key `K`
* - `false` otherwise
* @group Accessors
* @since 4.0.0
*/
export declare function has<K, V>(key: K, t: T<K, V>): boolean | never;
/**
* Returns a unary function which checks if a TypedMap has a key `K`
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const m = TypedMap.make(Str, Num, [["hello", 100]])
* const hasHello = TypedMap.has("hello")
*
* hasHello(m) // true
* hasHello(m) // false
* ```
*
* @template K the key type
* @param key the key
* @returns the unary function which accepts a TypedMap and returns
* - `true` if the TypedMap has a key `K`
* - `false` otherwise
* @group Accessors
* @since 4.0.0
*/
export declare function has<K, V>(key: K): <V>(t: T<K, V>) => boolean | never;
/**
* Returns an iterable of keys in the map
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const m = TypedMap.make(Str, Num, [["a", 1], ["b", 2]])
*
* Array.from(TypedMap.keys(m)) // ["a", "b"]
* ```
*
* @template K the key type
* @template V the value type
* @param t the TypedMap
* @returns the keys iterable
* @group Accessors
* @since 4.0.0
*/
export declare const keys: <K, V>(t: T<K, V>) => IterableIterator<K>;
/**
* Returns the number of elements in the Map
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const m = TypedMap.make(Str, Num, [["a", 1], ["b", 2]])
*
* TypedMap.size(m) // 2
* ```
*
* @template K the key type
* @template V the value type
* @param t the TypedMap
* @returns the TypedMap's size
* @group Accessors
* @since 4.0.0
*/
export declare const size: <K, V>(t: T<K, V>) => number;
/**
* Returns an iterable of values in the map
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const m = TypedMap.make(Str, Num, [["a", 1], ["b", 2]])
*
* Array.from(TypedMap.values(m)) // [1, 2]
* ```
*
* @template K the key type
* @template V the value type
* @param t the TypedMap
* @returns the keys iterable
* @group Accessors
* @since 4.0.0
*/
export declare const values: <K, V>(t: T<K, V>) => IterableIterator<V>;
/**
* Removes an entry `K` from a TypedMap `T<K, V>` if any and returns a new TypedMap
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const m0 = TypedMap.make(Str, Num, [['a', 0], ['b', 1]])
* const m1 = TypedMap.delete('a', m0)
*
* TypedMap.keys(m1) // ['b']
* ```
*
* @template K the key type
* @template V the value type
* @param key the key
* @param t the TypedMap
* @returns the new TypedMap
* @group Operators
* @since 4.0.0
*/
declare function _delete<K, V>(key: K, t: T<K, V>): T<K, V>;
/**
* Returns a unary function which removes an entry `K` from a TypedMap `T<K, V>` if any and returns a new TypedMap
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const m0 = TypedMap.make(Str, Num, [['a', 0], ['b', 1]])
* const m1 = TypedMap.make(Str, Num, [['a', 0], ['c', 1]])
* const deleteA = TypedMap.delete("a")
*
* TypedMap.keys(deleteA(m0)) // ['b']
* TypedMap.keys(deleteA(m1)) // ['c']
* ```
*
* @template K the key type
* @param key the key
* @returns the unary function which deletes the key and returns the new TypedMap
* @group Operators
* @since 4.0.0
*/
declare function _delete<K>(key: K): <V>(t: T<K, V>) => T<K, V>;
export { _delete as delete };
/**
* Sets a new value `V` at the key `K` for a TypedMap `T<K, V>`.
*
* This will not mutate the original map and will return a new TypedMap `T<K, V>`
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const m0 = TypedMap.make(Str, Num)
* const m1 = TypedMap.set("hello", 100, m0)
*
* Array.from(TypedMap.values(m0)) // []
* Array.from(TypedMap.values(m1)) // [100]
* ```
*
* @template K the key type
* @template V the value type
* @param a the key
* @param b the value
* @param c the TypedMap
* @returns the new TypedMap
* @group Operators
* @since 4.0.0
*/
export declare function set<K, V>(a: K, b: V, c: T<K, V>): T<K, V>;
/**
* Returns a unary function which sets a new value `V` at the key `K` for a TypedMap `T<K, V>`.
*
* This will not mutate the original map and will return a new TypedMap `T<K, V>`
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const m0 = TypedMap.make(Str, Num)
* const setHello = TypedMap.set("hello", 100);
*
* Array.from(TypedMap.values(setHello(m1))) // [100]
* Array.from(TypedMap.values(m0)) // []
* ```
*
* @template K the key type
* @template V the value type
* @param a the key
* @param b the value
* @returns the unary function
* @group Operators
* @since 4.0.0
*/
export declare function set<K, V>(a: K, b: V): Fn.Unary<T<K, V>, T<K, V>>;
/**
* Returns a binary function which sets a new value `V` at the key `K` for a TypedMap `T<K, V>`.
*
* This will not mutate the original map and will return a new TypedMap `T<K, V>`
*
* @example
*
* ```ts
* import { TypedMap, Str, Num } from 'tiinvo'
*
* const m0 = TypedMap.make(Str, Num)
* const set = TypedMap.set(m0);
*
* Array.from(TypedMap.values(set("hello", 100))) // [100]
* Array.from(TypedMap.values(set("world", 200))) // [200]
* Array.from(TypedMap.values(m0)) // []
* ```
*
* @template K the key type
* @template V the value type
* @param a the key
* @param b the TypedMap
* @returns the unary function
* @group Operators
* @since 4.0.0
*/
export declare function set<K, V>(a: T<K, V>): Fn.Binary<K, V, T<K, V>>;