@freeword/meta/built/src/lib/UF.d.ts

Meta package for Freeword: exports all core types, constants, and utilities from the src/ directory.

import * as NodeUtil from 'node:util';
import type * as TY from '../types.ts';
import * as JSPrintf from 'sprintf-js';
export type * from '../types.ts';
export * from './Streaming.ts';
export * from './Random.ts';
export * from '../UtilityConsts.ts';
export * from './Rot13.ts';
export { badOutcome, throwable } from './Outcome.ts';
export declare const sprintf: typeof JSPrintf.sprintf, vsprintf: typeof JSPrintf.vsprintf;
export type ObjKey = string | symbol;
export type ClxnKey = string | number | symbol;
export type ReadonlyCollection<KT extends ClxnKey = string, VT = any> = Record<KT, VT> | readonly VT[];
export type ObjKVFunc<RT, VT = any, KT extends ClxnKey = string> = (value: VT, keyOrIndex: KT, index: number, ...args: any) => RT;
export type ArrKVFunc<RT, VT = any> = (value: VT, keyOrIndex: number, index: number, ...args: any) => RT;
export type KVFunc<RT, VT = any, KT = string | number> = (value: VT, keyOrIndex: KT, index: number, ...args: any) => RT;
/** @returns a bag with keys a, b, ... z and values of type VT */
export declare function alphabetLookupBag<VT>(seed: VT | ((ltr: TY.AtoZlo) => VT)): Record<TY.AtoZlo, VT>;
/** Assign a **non-enumerable**, writable, configurable property to an object
 * See also {@link setNormalProp} and {@link decorate}
 * @param   obj     - The object to decorate
 * @param   key     - The key to decorate the object with
 * @param   value   - The value to decorate the object with
 * @returns           The value
 */
export declare function adorn<VT>(obj: object, key: string, value: VT): VT;
/** Assign an enumerable, writable, configurable property to an object
 * See also {@link adorn} and {@link decorate}
 * @param   obj     - The object to decorate
 * @param   key     - The key to decorate the object with
 * @param   value   - The value to decorate the object with
 * @returns           The value
 */
export declare function setNormalProp<VT>(obj: object, key: string, value: VT): VT;
export declare function setNormalProps<OT extends Record<string, any>, VT extends Record<string, any>>(obj: OT, vals: VT): OT & VT;
export declare function setHiddenProps<OT extends Record<string, any>, VT extends Record<string, any>>(obj: OT, vals: VT): OT & VT;
/** Assign non-enumerable, writable, configurable properties to an object
 * See also {@link adorn} and {@link decorate}
 * @param   obj - The object to decorate
 * @param   vals - The values to decorate the object with
 * @returns The decorated object
 */
export declare function decorate<OT extends Record<string, any>, VT extends Record<string, any>>(obj: OT, vals: VT): OT & VT;
/** Get the own properties of an object
 *
 * @param   obj - The object to get the own properties of
 * @returns       The own properties of the object; empty object if nil
 */
export declare function ownProps(obj: object | null | undefined): TY.Bag<TypedPropertyDescriptor<any>>;
/** Get the own property names of an object
 *
 * @param   obj - The object to get the own property names of
 * @returns       The own property names of the object; empty array if nil
 */
export declare function ownPropnames(obj: object | null | undefined): string[];
/** Get the property names of the **first parent prototype** of an object
 *
 * @param   obj - The object to get the prototype property names of
 * @returns       The prototype property names of the object; empty array if nil
 */
export declare function protoPropnames(obj: object | null | undefined): string[];
/** Get the property descriptor of a property of the **first parent prototype** of an object
 *
 * @param   obj       - The object to get the property descriptor of
 * @param   propname  - The name of the property to get the descriptor of
 * @returns           The property descriptor of the property; undefined if not found
 */
export declare function protoProp<VT>(obj: object, propname: TY.Fieldname): TypedPropertyDescriptor<VT> | undefined;
/** Get the property descriptor of a property of an object
 *
 * @param   obj       - The object to get the property descriptor of
 * @param   propname  - The name of the property to get the descriptor of
 * @returns           The property descriptor of the property; undefined if not found
 */
export declare function ownProp<VT>(obj: object, propname: TY.Fieldname): TypedPropertyDescriptor<VT> | undefined;
/** Get the first property descriptor found ascending the prototype chain
 * for a given property name
 *
 * @param   obj       - The object to get the property descriptor of
 * @param   propname  - The name of the property to get the descriptor of
 * @param   depth     - The depth of the prototype chain to search
 * @returns             The property descriptor of the property; undefined if not found
 */
export declare function getProp<VT>(obj: object, propname: TY.Fieldname, depth?: number): TypedPropertyDescriptor<VT> | undefined;
export declare function bagsize(bag: TY.AnyBag | any[]): number;
export interface PrettifyFieldOpts {
    /** per line for arrays    */ chunkSize?: number | undefined;
    /** width per arr item     */ colwd?: number | undefined;
    /** primary key width      */ keywd?: number | undefined;
    /** prefix bag with key    */ key?: string | undefined;
    /** omit the brackets?     */ naked?: boolean | undefined;
    /** indent for arrays      */ indent?: string | number | undefined;
}
export interface PrettifyOpts extends PrettifyFieldOpts {
    /** omit the brackets?        */ naked?: boolean | undefined;
    /** always align array slots? */ chunkArrays?: boolean | undefined;
}
/**
 * Pretty-print an array of strings in chunks
 *
 * @param   arr - The array to pretty-print
 * @param   opts - The options for pretty-printing
 * @returns       The pretty-printed array
 */
export declare function prettifyInChunks(arr: readonly string[], { chunkSize, colwd, key, indent }?: PrettifyOpts): string;
export declare function prettifyArray(arr: readonly any[], opts?: PrettifyOpts): string;
export declare function prettifySet(set: Set<any>, { key, ...opts }?: PrettifyOpts): string;
export declare function inspectify(val: any, _opts?: NodeUtil.InspectOptions): string;
export declare function kfy(key: any, opts?: PrettifyOpts): string;
export declare function prettifyField(val: any, opts?: PrettifyOpts): string;
export declare function prettify(obj: object, { key, naked, ...opts }?: PrettifyOpts): string;
/**
 * Calls func with every element of collection (array, object, etc)
 * producing a bag using the [key, value] pairs returned by func
 *
 * * func: a function that accepts (val, collectionKey, seq, collection) => [resultKey, resultVal]
 *   - val: the value of the element in the collection
 *   - key: the key of the element in the collection: a number (for arrays) or string (for objects)
 *   - seq: the index of the element in the collection, 0...size
 *   - collection: the collection being processed
 *   - returns [resultKey, resultVal]
 * @returns bag with keys of type KT and values of type RVT (the return value of func)
 *
 * @example
 *
 *     rebag(bag, (val, key) => { const obj = lookup(key); return [obj.id, obj] }
 *     // { 'mbr.lotr:sam': { ... }, 'mbr.lotr:frodo': { ... } }
 */
export declare function rebag<RVT = any, IVT = any, RKT extends ObjKey = string>(clxn: readonly IVT[], func: ArrKVFunc<[RKT, RVT], IVT>): Record<RKT, RVT>;
export declare function rebag<RVT = any, OT extends object = object, RKT extends ObjKey = string, IKT = any>(clxn: OT, func: ObjKVFunc<[RKT, RVT], OT[keyof OT], keyof OT>): Record<RKT, RVT>;
export declare function rebag<RVT = any, IVT = any, RKT extends ObjKey = ObjKey, IKT extends ObjKey = string>(clxn: ReadonlyCollection<IKT, IVT>, func: KVFunc<[RKT, RVT], IVT, IKT>): Record<RKT, RVT>;
/**
 * Calls func with every element of collection (array, object, etc)
 * and returns an object with the result, using the values of the original
 * elements as keys of the new bag.
 *
 * func should expect same args as map and return the value for each prop
 *    func(val, key/ii, collection) => val // for an object
 *
 * * func: a function that accepts (val, collectionKey, seq, collection) => val
 *   - val: the value of the element in the collection
 *   - key: the key of the element in the collection: a number (for arrays) or string (for objects)
 *   - seq: the index of the element in the collection, 0...size
 *   - collection: the collection being processed
 * @returns bag with keys of type KT and values of type RVT (the return value of func)
 *   - given an array of KT[],               returns a record with keys of type KT and values of type RVT
 *   - given a bag with values of type VT,   returns a record with keys of type VT and values of type RVT
 *   - given a bag with string keys,         returns a record with keys of type string and values of type RVT
 *
 * In all cases, the **values** of the collection become the **keys** of the new bag.
 *
 * @example
 *   objectify(['a', 'b'],   (vv, ii, ii, clxn) => vv + ii)      // { a: 'a0', b: 'b1' }
 *   objectify({x: 1, y: 2}, (vv, kk, ii, clxn) => vv * ii)      // { x: 0, y: 2 }
 *   objectify(['sam', 'frodo'], (name) => `${name}_id`)         // { sam: 'sam_id', frodo: 'frodo_id' }
 */
export declare function objectify<RT = any, KT extends ClxnKey = string>(clxn: readonly KT[], func: ArrKVFunc<RT, KT>): Record<KT, RT>;
export declare function objectify<RT = any, OT extends TY.AnyBag = TY.AnyBag, VT extends ClxnKey = OT[keyof OT]>(clxn: OT, func: ObjKVFunc<VT, OT[keyof OT], keyof OT>): Record<VT, RT>;
export declare function objectify<RT = any, KT extends ClxnKey = string, VT = any>(clxn: ReadonlyCollection<KT, VT>, func: KVFunc<RT, KT, VT>): Record<KT, RT>;
export declare function bagslice<VT extends object>(bag: VT, start: number | undefined, end: number | undefined): Partial<VT>;
type PairSortFn<VT extends object, KT extends keyof VT = keyof VT> = ((entry: [key: KT, val: VT[KT]]) => any);
export declare function sortOnKeys<VT extends object, KT extends keyof VT = keyof VT>([key, _val]: [KT, VT[KT]]): KT;
export declare function sortOnNumkeys<VT extends object, KT extends keyof VT = keyof VT>([key, _val]: [KT, VT[KT]]): number;
/** Sort a bag by a funtion -- by default, its keys.
 * @note **by default, keys that parse as positive integers (1, 2, 3, ...) will appear first in retrieval order**.
 * This is part of the spec for Object.
 * @example { '1': 1, '2': 2, '-1': -1, '0.9': 0.9, '1.1': 1.1 }
 * If you use the magic function `sortOnNumkeys`,
 * keys that stringify as integers will be reinserted as `x.0`:
 * @example { '-1.0': -1, '0.9': 0.9, '1.0': 1, '1.1': 1.1, '2.0': 2 }
 */
export declare function bagsort<VT extends object, KT extends keyof VT = keyof VT>(bag: VT, sortfn?: PairSortFn<VT, KT>, { mungeNumKeys }?: {
    mungeNumKeys?: boolean;
}): VT;
/**
 * Sleep for one tick (i.e. let everyone else have a turn)
 * @returns true
 */
export declare function sleepNextTick(): Promise<true>;
/**
 * Sleep for a given number of milliseconds
 * @param ms       - The number of milliseconds to sleep
 * @param nextTick - Whether to sleep for one tick before starting the sleep
 * @note IMPORTANT: if nextTick is true, the sleep will be delayed by
 *   the duration given PLUS an unknowable amount of time
 * @returns true
 */
export declare function sleep(ms: number, awakeNextTick?: boolean): Promise<true>;
export declare function catiters(...iters: TY.AnyIterable<any>[]): AsyncGenerator<any, void, any>;
export declare function isNode(): boolean;
export declare function isBrowser(): boolean;
//# sourceMappingURL=UF.d.ts.map