iterable-linq-utility 0.10.0 → 0.11.0

package/dist/index.d.cts

@@ -319,10 +319,12 @@ declare function every<T>(iterable: Iterable<T>, predicate: Predicate<T>): boole
 
 /**
  * Adds a method to every chain, including the chains created before the call.
- * Declare the method first by augmenting `IIterableLinq`, then register it once, at application start-up.
- * @param name - the method name; it must not exist yet (library methods, earlier extensions, `Object.prototype` members)
+ * Declare the method first by augmenting `IIterableLinq`, then register it at application start-up.
+ * Registering a name added by an earlier `extend` again replaces its implementation, so a module that runs twice
+ * (hot module replacement, a test runner that re-imports it) does not throw: the last registration wins.
+ * @param name - the method name; a new name or one added by an earlier `extend`, not a library method or an `Object.prototype` member
  * @param implementation - the method; `this` is the chain, typed `IIterableLinq<unknown>`
- * @throws Error if `name` already exists (use `override` to replace it), is empty, or `implementation` is not a function
+ * @throws Error if `name` is a library method (use `override` to replace it), an `Object.prototype` member or a name used by the chain instances, is empty, or `implementation` is not a function
  * @example
  * ```ts
  * declare module 'iterable-linq-utility' {
@@ -564,6 +566,47 @@ declare function forEachAsync<T>(iterable: Iterable<T>, action: AsyncAction<T>):
  */
 export declare function from<T>(iterable: Iterable<T>): IIterableLinq<T>;
 
+/**
+ * Starts a chain over the properties of `object`: its entries, its keys, its values or its property descriptors.
+ * With the default options it yields what `Object.entries` returns: the own, enumerable, string keys.
+ * - `options.yield`: `'entries'` (default) `[key, value]`, `'keys'`, `'values'`, or `'descriptors'` `[key, descriptor, owner]` without calling the getters.
+ * - `options.inherited` also reads the prototype chain, up to `Object.prototype` excluded; a key is yielded once, from the nearest object that has it, like `for…in`.
+ * - `options.nonEnumerable` also reads the non-enumerable properties, `options.symbols` the symbol keys.
+ * - Each run of the chain reads the object again: the keys of an object when the iteration reaches it, a value when it is yielded.
+ * @param object - the object to read
+ * @param options - `yield`, `inherited`, `nonEnumerable` and `symbols`
+ * @returns a chain of the properties of `object`
+ * @throws Error if `object` is not an object or a function, `options` is not an object, `yield` is not one of its values, or a flag is not a boolean
+ * @example
+ * ```ts
+ * IterableLinq.fromObject({ a: 1, b: 2 }).collectToArray();                    // [['a', 1], ['b', 2]]
+ * IterableLinq.fromObject({ a: 1, b: 2 }, { yield: 'keys' }).collectToArray();   // ['a', 'b']
+ * IterableLinq.fromObject({ a: 1, b: 2 }, { yield: 'values' }).collectToArray(); // [1, 2]
+ * ```
+ * @since 0.11.0
+ */
+export declare function fromObject<O extends object, const Options extends IObjectOptions = IObjectDefaultOptions>(object: O, options?: Options): IIterableLinq<ObjectItem<O, Options>>;
+
+/**
+ * Returns the properties of `object`: its entries, its keys, its values or its property descriptors.
+ * With the default options it yields what `Object.entries` returns: the own, enumerable, string keys.
+ * - `inherited` also reads the prototype chain, up to `Object.prototype` excluded; a key is yielded once, from the nearest object that has it, like `for…in`.
+ * - `nonEnumerable` also reads the non-enumerable properties, `symbols` the symbol keys.
+ * - The keys of an object are read when the iteration reaches it, a value when it is yielded: each run reads the object again.
+ * @operation `Transformation`
+ * @param object - the object to read
+ * @param options - `yield` (`'entries'`, `'keys'`, `'values'` or `'descriptors'`), `inherited`, `nonEnumerable` and `symbols`
+ * @returns a lazy, re-runnable `Iterable` of the properties of `object`
+ * @throws Error if `object` is not an object or a function, `options` is not an object, `yield` is not one of its values, or a flag is not a boolean
+ * @example
+ * ```ts
+ * Array.from(Functions.fromObject({ a: 1, b: 2 })); // [['a', 1], ['b', 2]]
+ * Array.from(Functions.fromObject({ a: 1, b: 2 }, { yield: 'keys' })); // ['a', 'b']
+ * ```
+ * @since 0.11.0
+ */
+declare function fromObject_2<O extends object, const Options extends IObjectOptions = IObjectDefaultOptions>(object: O, options?: Options): Iterable<ObjectItem<O, Options>>;
+
 /**
  * Starts a chain of numbers from 0 up to, but not including, `end`.
  * - `options.step` is the distance between two values (default 1); its sign is ignored, the direction comes from the sign of `end`.
@@ -630,6 +673,7 @@ declare namespace Functions {
         flatMap,
         forEach,
         forEachAsync,
+        fromObject_2 as fromObject,
         includes,
         indexOf,
         join,
@@ -1661,6 +1705,32 @@ declare function includes<T>(iterable: Iterable<T>, value: T): boolean;
  */
 declare function indexOf<T>(iterable: Iterable<T>, value: T): number;
 
+/**
+ * The options of `fromObject` when none are given: the type of the values follows `Object.entries`.
+ * @since 0.11.0
+ */
+export declare interface IObjectDefaultOptions extends IObjectOptions {
+    yield?: 'entries';
+    inherited?: false;
+    nonEnumerable?: false;
+    symbols?: false;
+}
+
+/**
+ * Options of `fromObject`. The defaults read what `Object.keys` reads: the own, enumerable, string keys.
+ * @since 0.11.0
+ */
+export declare interface IObjectOptions {
+    /** `'entries'` (default) yields `[key, value]`, `'keys'` the keys, `'values'` the values, `'descriptors'` `[key, descriptor, owner]` without calling the getters. */
+    yield?: ObjectYield;
+    /** Also reads the properties of the prototype chain, up to `Object.prototype` excluded; defaults to `false`. */
+    inherited?: boolean;
+    /** Also reads the non-enumerable properties; defaults to `false`. */
+    nonEnumerable?: boolean;
+    /** Also reads the symbol keys; defaults to `false`. */
+    symbols?: boolean;
+}
+
 /**
  * Options of `range`.
  * @since 0.1.0
@@ -1811,6 +1881,39 @@ declare function memoize<T>(iterable: Iterable<T>, options?: IMemoizeOptions): I
  */
 declare function min<T>(iterable: Iterable<T>, comparer?: Comparer<T>): T | undefined;
 
+/**
+ * The type of the values of `fromObject(object, options)`, chosen by `options.yield` (default `'entries'`).
+ * @since 0.11.0
+ */
+export declare type ObjectItem<O, Options extends IObjectOptions> = ObjectItemOf<O, Options, Options extends {
+    yield: infer Y;
+} ? Y : Options extends {
+    yield?: infer Y;
+} ? Y | undefined : undefined>;
+
+/** Distributes over `Y`, so a `yield` typed as a union gives the union of the items; `undefined` gives the entries. */
+declare type ObjectItemOf<O, Options extends IObjectOptions, Y> = Y extends 'keys' ? ObjectKey<O, Options> : Y extends 'values' ? ObjectValue<O, Options> : Y extends 'descriptors' ? [ObjectKey<O, Options>, PropertyDescriptor, object] : [ObjectKey<O, Options>, ObjectValue<O, Options>];
+
+/**
+ * The type of the keys `fromObject` yields: the keys of `O` as strings, as they are at runtime,
+ * or `string` (and `symbol`) when the options read keys that `O` does not declare.
+ * @since 0.11.0
+ */
+export declare type ObjectKey<O, Options extends IObjectOptions> = ReadsWide<Options> extends true ? string | (ReadsSymbols<Options> extends true ? symbol : never) : `${Extract<keyof O, string | number>}` | (ReadsSymbols<Options> extends true ? Extract<keyof O, symbol> : never);
+
+/**
+ * The type of the values `fromObject` yields: the values of the keys of `O` it reads, or `unknown`
+ * when the options read keys that `O` does not declare.
+ * @since 0.11.0
+ */
+export declare type ObjectValue<O, Options extends IObjectOptions> = ReadsWide<Options> extends true ? unknown : O[Extract<keyof O, string | number> | (ReadsSymbols<Options> extends true ? Extract<keyof O, symbol> : never)];
+
+/**
+ * What `fromObject` yields for each property.
+ * @since 0.11.0
+ */
+export declare type ObjectYield = 'entries' | 'keys' | 'values' | 'descriptors';
+
 /**
  * Replaces an existing method of every chain: a library method or one added with `extend`.
  * Typical use: a library release adds a method with the same name as one of your extensions,
@@ -1890,6 +1993,21 @@ declare function range(end: number, options?: IRangeOptions): Iterable<number>;
  */
 declare function range(start: number, end: number, options?: IRangeOptions): Iterable<number>;
 
+declare type ReadsSymbols<Options extends IObjectOptions> = Options extends {
+    yield?: unknown;
+    inherited?: unknown;
+    nonEnumerable?: unknown;
+    symbols?: false;
+} ? false : true;
+
+/** `true` when the options may read keys that are not in `keyof O`: inherited or non-enumerable ones. */
+declare type ReadsWide<Options extends IObjectOptions> = Options extends {
+    yield?: unknown;
+    inherited?: false;
+    nonEnumerable?: false;
+    symbols?: unknown;
+} ? false : true;
+
 /**
  * Accumulates the values of `iterable` into a single result, starting from the first value.
  * @operation `Action`

package/dist/index.d.ts

@@ -319,10 +319,12 @@ declare function every<T>(iterable: Iterable<T>, predicate: Predicate<T>): boole
 
 /**
  * Adds a method to every chain, including the chains created before the call.
- * Declare the method first by augmenting `IIterableLinq`, then register it once, at application start-up.
- * @param name - the method name; it must not exist yet (library methods, earlier extensions, `Object.prototype` members)
+ * Declare the method first by augmenting `IIterableLinq`, then register it at application start-up.
+ * Registering a name added by an earlier `extend` again replaces its implementation, so a module that runs twice
+ * (hot module replacement, a test runner that re-imports it) does not throw: the last registration wins.
+ * @param name - the method name; a new name or one added by an earlier `extend`, not a library method or an `Object.prototype` member
  * @param implementation - the method; `this` is the chain, typed `IIterableLinq<unknown>`
- * @throws Error if `name` already exists (use `override` to replace it), is empty, or `implementation` is not a function
+ * @throws Error if `name` is a library method (use `override` to replace it), an `Object.prototype` member or a name used by the chain instances, is empty, or `implementation` is not a function
  * @example
  * ```ts
  * declare module 'iterable-linq-utility' {
@@ -564,6 +566,47 @@ declare function forEachAsync<T>(iterable: Iterable<T>, action: AsyncAction<T>):
  */
 export declare function from<T>(iterable: Iterable<T>): IIterableLinq<T>;
 
+/**
+ * Starts a chain over the properties of `object`: its entries, its keys, its values or its property descriptors.
+ * With the default options it yields what `Object.entries` returns: the own, enumerable, string keys.
+ * - `options.yield`: `'entries'` (default) `[key, value]`, `'keys'`, `'values'`, or `'descriptors'` `[key, descriptor, owner]` without calling the getters.
+ * - `options.inherited` also reads the prototype chain, up to `Object.prototype` excluded; a key is yielded once, from the nearest object that has it, like `for…in`.
+ * - `options.nonEnumerable` also reads the non-enumerable properties, `options.symbols` the symbol keys.
+ * - Each run of the chain reads the object again: the keys of an object when the iteration reaches it, a value when it is yielded.
+ * @param object - the object to read
+ * @param options - `yield`, `inherited`, `nonEnumerable` and `symbols`
+ * @returns a chain of the properties of `object`
+ * @throws Error if `object` is not an object or a function, `options` is not an object, `yield` is not one of its values, or a flag is not a boolean
+ * @example
+ * ```ts
+ * IterableLinq.fromObject({ a: 1, b: 2 }).collectToArray();                    // [['a', 1], ['b', 2]]
+ * IterableLinq.fromObject({ a: 1, b: 2 }, { yield: 'keys' }).collectToArray();   // ['a', 'b']
+ * IterableLinq.fromObject({ a: 1, b: 2 }, { yield: 'values' }).collectToArray(); // [1, 2]
+ * ```
+ * @since 0.11.0
+ */
+export declare function fromObject<O extends object, const Options extends IObjectOptions = IObjectDefaultOptions>(object: O, options?: Options): IIterableLinq<ObjectItem<O, Options>>;
+
+/**
+ * Returns the properties of `object`: its entries, its keys, its values or its property descriptors.
+ * With the default options it yields what `Object.entries` returns: the own, enumerable, string keys.
+ * - `inherited` also reads the prototype chain, up to `Object.prototype` excluded; a key is yielded once, from the nearest object that has it, like `for…in`.
+ * - `nonEnumerable` also reads the non-enumerable properties, `symbols` the symbol keys.
+ * - The keys of an object are read when the iteration reaches it, a value when it is yielded: each run reads the object again.
+ * @operation `Transformation`
+ * @param object - the object to read
+ * @param options - `yield` (`'entries'`, `'keys'`, `'values'` or `'descriptors'`), `inherited`, `nonEnumerable` and `symbols`
+ * @returns a lazy, re-runnable `Iterable` of the properties of `object`
+ * @throws Error if `object` is not an object or a function, `options` is not an object, `yield` is not one of its values, or a flag is not a boolean
+ * @example
+ * ```ts
+ * Array.from(Functions.fromObject({ a: 1, b: 2 })); // [['a', 1], ['b', 2]]
+ * Array.from(Functions.fromObject({ a: 1, b: 2 }, { yield: 'keys' })); // ['a', 'b']
+ * ```
+ * @since 0.11.0
+ */
+declare function fromObject_2<O extends object, const Options extends IObjectOptions = IObjectDefaultOptions>(object: O, options?: Options): Iterable<ObjectItem<O, Options>>;
+
 /**
  * Starts a chain of numbers from 0 up to, but not including, `end`.
  * - `options.step` is the distance between two values (default 1); its sign is ignored, the direction comes from the sign of `end`.
@@ -630,6 +673,7 @@ declare namespace Functions {
         flatMap,
         forEach,
         forEachAsync,
+        fromObject_2 as fromObject,
         includes,
         indexOf,
         join,
@@ -1661,6 +1705,32 @@ declare function includes<T>(iterable: Iterable<T>, value: T): boolean;
  */
 declare function indexOf<T>(iterable: Iterable<T>, value: T): number;
 
+/**
+ * The options of `fromObject` when none are given: the type of the values follows `Object.entries`.
+ * @since 0.11.0
+ */
+export declare interface IObjectDefaultOptions extends IObjectOptions {
+    yield?: 'entries';
+    inherited?: false;
+    nonEnumerable?: false;
+    symbols?: false;
+}
+
+/**
+ * Options of `fromObject`. The defaults read what `Object.keys` reads: the own, enumerable, string keys.
+ * @since 0.11.0
+ */
+export declare interface IObjectOptions {
+    /** `'entries'` (default) yields `[key, value]`, `'keys'` the keys, `'values'` the values, `'descriptors'` `[key, descriptor, owner]` without calling the getters. */
+    yield?: ObjectYield;
+    /** Also reads the properties of the prototype chain, up to `Object.prototype` excluded; defaults to `false`. */
+    inherited?: boolean;
+    /** Also reads the non-enumerable properties; defaults to `false`. */
+    nonEnumerable?: boolean;
+    /** Also reads the symbol keys; defaults to `false`. */
+    symbols?: boolean;
+}
+
 /**
  * Options of `range`.
  * @since 0.1.0
@@ -1811,6 +1881,39 @@ declare function memoize<T>(iterable: Iterable<T>, options?: IMemoizeOptions): I
  */
 declare function min<T>(iterable: Iterable<T>, comparer?: Comparer<T>): T | undefined;
 
+/**
+ * The type of the values of `fromObject(object, options)`, chosen by `options.yield` (default `'entries'`).
+ * @since 0.11.0
+ */
+export declare type ObjectItem<O, Options extends IObjectOptions> = ObjectItemOf<O, Options, Options extends {
+    yield: infer Y;
+} ? Y : Options extends {
+    yield?: infer Y;
+} ? Y | undefined : undefined>;
+
+/** Distributes over `Y`, so a `yield` typed as a union gives the union of the items; `undefined` gives the entries. */
+declare type ObjectItemOf<O, Options extends IObjectOptions, Y> = Y extends 'keys' ? ObjectKey<O, Options> : Y extends 'values' ? ObjectValue<O, Options> : Y extends 'descriptors' ? [ObjectKey<O, Options>, PropertyDescriptor, object] : [ObjectKey<O, Options>, ObjectValue<O, Options>];
+
+/**
+ * The type of the keys `fromObject` yields: the keys of `O` as strings, as they are at runtime,
+ * or `string` (and `symbol`) when the options read keys that `O` does not declare.
+ * @since 0.11.0
+ */
+export declare type ObjectKey<O, Options extends IObjectOptions> = ReadsWide<Options> extends true ? string | (ReadsSymbols<Options> extends true ? symbol : never) : `${Extract<keyof O, string | number>}` | (ReadsSymbols<Options> extends true ? Extract<keyof O, symbol> : never);
+
+/**
+ * The type of the values `fromObject` yields: the values of the keys of `O` it reads, or `unknown`
+ * when the options read keys that `O` does not declare.
+ * @since 0.11.0
+ */
+export declare type ObjectValue<O, Options extends IObjectOptions> = ReadsWide<Options> extends true ? unknown : O[Extract<keyof O, string | number> | (ReadsSymbols<Options> extends true ? Extract<keyof O, symbol> : never)];
+
+/**
+ * What `fromObject` yields for each property.
+ * @since 0.11.0
+ */
+export declare type ObjectYield = 'entries' | 'keys' | 'values' | 'descriptors';
+
 /**
  * Replaces an existing method of every chain: a library method or one added with `extend`.
  * Typical use: a library release adds a method with the same name as one of your extensions,
@@ -1890,6 +1993,21 @@ declare function range(end: number, options?: IRangeOptions): Iterable<number>;
  */
 declare function range(start: number, end: number, options?: IRangeOptions): Iterable<number>;
 
+declare type ReadsSymbols<Options extends IObjectOptions> = Options extends {
+    yield?: unknown;
+    inherited?: unknown;
+    nonEnumerable?: unknown;
+    symbols?: false;
+} ? false : true;
+
+/** `true` when the options may read keys that are not in `keyof O`: inherited or non-enumerable ones. */
+declare type ReadsWide<Options extends IObjectOptions> = Options extends {
+    yield?: unknown;
+    inherited?: false;
+    nonEnumerable?: false;
+    symbols?: unknown;
+} ? false : true;
+
 /**
  * Accumulates the values of `iterable` into a single result, starting from the first value.
  * @operation `Action`