linqx 0.2.0 → 0.3.2

package/README.md

@@ -1,151 +1,245 @@
 # linqx
 
-Fork of the original [linq](https://github.com/mihaifm/linq) for JavaScript, updated with modern improvements and API changes.
+Modern fork of the original [linq](https://github.com/mihaifm/linq) for JavaScript.
 
-It contains all the original .NET methods plus a few additions.
+linqx keeps the familiar LINQ-style API while adding modern exports, new utility methods, improved TypeScript support, and active maintenance.
 
-Written in pure JavaScript with no dependencies.
+Written in TypeScript with no runtime dependencies.
 
-## Examples
+---
 
-```js
-// C# LINQ - delegate
-Enumerable.Range(1, 10)
-    .Where(delegate(int i) { return i % 3 == 0; })
-    .Select(delegate(int i) { return i * 10; });
+# Key Differences from linq
 
-// linq.js - anonymous function
-Enumerable.range(1, 10)
-    .where(function(i) { return i % 3 == 0; })
-    .select(function(i) { return i * 10; });
-```
+## 1. Named Export Added
+
+The original package only exposed a default export.
 
-```js
-// C# LINQ - lambda
-Enumerable.Range(1, 10).Where((i) => i % 3 == 0).Select((i) => i * 10);
+linqx also provides:
 
-// linq.js - arrow function
-Enumerable.range(1, 10).where((i) => i % 3 == 0).select((i) => i * 10);
+```ts
+export { Enumerable };
 ```
 
-```js
-// C# LINQ - anonymous type
-array.Select((val, i) => new { Value: val, Index: i }());
+This makes extensions, wrappers, and custom integrations cleaner and more flexible for `typescript`.
 
-// linq.js - object literal
-Enumerable.from(array).select((val, i) => ({ value: val, index: i }));
-```
+Example:
 
-See [sample/tutorial.js](https://github.com/mihaifm/linq/blob/master/sample/tutorial.js) and the [test](https://github.com/mihaifm/linq/tree/master/test) folder for more examples.
+```ts
+// enumerable.extensions.ts
+import { Enumerable } from "linqx";
 
-# Usage
+declare module "linqx" {
+  namespace Enumerable {
+    export function crossJoin<T>(this: Enumerable.IEnumerable<T>): Enumerable.IEnumerable<{ left: T; right: T; }>;
+  }
+}
+
+Enumerable.prototype.crossJoin = function <T>(this: Enumerable.IEnumerable<T>): Enumerable.IEnumerable<{ left: T; right: T; }> {
+  return Enumerable.from(crossJoinIterator(this));
+
+  function* crossJoinIterator(enumerable: Enumerable.IEnumerable<T>): Iterable<{ left: T; right: T; }> {
+    for (const item of enumerable) {
+      for (const otherItem of enumerable) {
+        yield { left: item, right: otherItem };
+      }
+    }
+  }
+};
+```
 
-## Node.js (ES modules)
+Useful when augmenting prototypes or writing reusable helpers.
 
-Install the latest version of the library with npm:
+---
 
-    npm install linq
+## 2. Additional APIs
 
-Load it in your code with the `import` syntax:
+linqx adds practical methods not available in the original package.
 
-```js
-import Enumerable from 'linq'
 
-let result = Enumerable.range(1, 10).where(i => i % 3 == 0).select(i => i * 10)
-console.log(result.toArray()) // [ 30, 60, 90 ]
+```ts
+whereIf(flag, predicate)
+page(pageNumber, pageSize)
+page({ pageNumber, pageSize })
+joinWith(separator)
+toMap(keySelector, valueSelector)
+chunk(size)
+index()
+position()
+withNeighbors()
+append(element)
+prepend(element)
+skipLast(count)
+takeLast(count)
+distinctBy(keySelector)
+exceptBy(keys, keySelector)
+intersectBy(keys, keySelector)
+unionBy(sequence, keySelector)
+countBy(keySelector)
+aggregateBy(keySelector, seed, accumulator)
+rightJoin(sequence, outerKeySelector, innerKeySelector, resultSelector)
+toSet()
 ```
 
-Because the library is an ES module, this code will only work if your project is also configured as an ES module. Add the following line in your `package.json` to make it an ES module:
+---
 
-```json
-"type": "module"
+# Installation
+
+```bash
+npm install linqx
 ```
 
-If you're not planning to use ES modules, check the CommonJS section below.
+---
+
+# Usage
+
+## ES Modules
 
-## Node.js (CommonJS modules)
+```ts
+import Enumerable from "linqx";
 
-Install version 3 of this library:
+const result = Enumerable
+  .range(1, 10)
+  .where(x => x % 3 === 0)
+  .select(x => x * 10)
+  .toArray();
+```
 
-    npm install linq@3
+---
 
-Load it with the `require` syntax:
+## Named Export
 
-```js
-const Enumerable = require('linq')
+```ts
+import { Enumerable } from "linqx";
 
-let count = Enumerable.range(1, 10).count(i => i < 5)
-console.log(count) // 4
+const values = Enumerable.from([1, 2, 3]);
 ```
 
-The [cjs](https://github.com/mihaifm/linq/tree/cjs) branch contains the source code for the CommonJS version of the library.
+---
 
 ## TypeScript
 
-Install the latest version of the library with npm.
+```ts
+import Enumerable from "linqx";
 
-Configure your compiler options in `tsconfig.json`
+const items: Enumerable.IEnumerable<number> = Enumerable.from([1, 2, 3]);
+```
 
-```json
-"compilerOptions": {
-    "target": "ES2020",
-    "moduleResolution": "node"
-}
+## Tutorial
+
+Build the package and run the TypeScript tutorial:
+
+```bash
+pnpm tutorial
 ```
 
-The library comes with a `d.ts` file containing type definitions for all the objects and methods, feel free to use them in your code:
+---
+
+## New API Examples
 
 ```ts
-import Enumerable from 'linq';
+// whereIf
+Enumerable
+  .from([1, 2, 3, 4])
+  .whereIf(true, x => x > 2)
+  .toArray();
+
+// chunk
+Enumerable
+  .from([1, 2, 3, 4, 5])
+  .chunk(2)
+  .toArray();
+// result: [[1, 2], [3, 4], [5]]
+
+// withNeighbors
+for (const { prev, item, next } of Enumerable.from([10, 20, 30]).withNeighbors()) {
+}
 
-type tnum = Enumerable.IEnumerable<number>;
-let x: tnum = Enumerable.from([1, 2, 3]);
+// position
+for (const { index, item, isFirst, isLast } of Enumerable.from(["a", "b", "c"]).position()) {
+}
+
+// Standard sequence helpers
+Enumerable.from([2, 3]).prepend(1).append(4).toArray();
+// result: [1, 2, 3, 4]
+
+Enumerable.from([1, 2, 3, 4]).skipLast(2).toArray();
+// result: [1, 2]
+
+Enumerable.from([1, 2, 3, 4]).takeLast(2).toArray();
+// result: [3, 4]
+
+// Key-based set operations
+Enumerable
+  .from([{ id: 1, name: "first" }, { id: 1, name: "second" }])
+  .distinctBy(item => item.id)
+  .toArray();
+// result: [{ id: 1, name: "first" }]
+
+Enumerable
+  .from([{ id: 1 }, { id: 2 }, { id: 3 }])
+  .exceptBy([2], item => item.id)
+  .toArray();
+// result: [{ id: 1 }, { id: 3 }]
+
+// Per-key aggregation
+Enumerable
+  .from(["a", "b", "a"])
+  .countBy(value => value)
+  .toArray();
+// result: [{ key: "a", value: 2 }, { key: "b", value: 1 }]
+
+Enumerable
+  .from([{ category: "a", amount: 2 }, { category: "a", amount: 3 }])
+  .aggregateBy(item => item.category, 0, (sum, item) => sum + item.amount)
+  .toArray();
+// result: [{ key: "a", value: 5 }]
+
+// Native Set materialization
+Enumerable.from([1, 1, 2]).toSet();
 ```
 
-## Deno
+`countBy` and `aggregateBy` return
+`Enumerable.IEnumerable<Enumerable.KeyValuePair<TKey, TValue>>`. Key-based methods accept an
+optional final comparison selector when keys need normalization, such as
+`key => key.toLowerCase()` for case-insensitive string keys.
 
-Import the library from deno.land. Use the `@deno-types` annotation to load type definitions:
+---
 
-```ts
-// @deno-types="https://deno.land/x/linq@4.0.0/linq.d.ts"
-import Enumerable from 'https://deno.land/x/linq@4.0.0/linq.js'
+# Migration from linq
+
+Most projects can switch directly:
 
-let radius = Enumerable.toInfinity(1).where(r => r * r * Math.PI > 10000).first()
+```diff
+-import Enumerable from "linq";
++import Enumerable from "linqx";
 ```
 
-You can also install locally with npm. Use the full file path when importing the library:
+The original string Lambda syntax is no longer supported. Pass JavaScript functions instead:
 
 ```ts
-// @deno-types="./node_modules/linq/linq.d.ts"
-import Enumerable from './node_modules/linq/linq.js'
+// supported
+Enumerable.from([1, 2, 3, 4]).where(value => value % 2 === 0);
+
+// not supported
+Enumerable.from([1, 2, 3, 4]).where("value => value % 2 === 0");
 ```
 
-## Browser
+---
 
-The minified version of the library is available in the [release](https://github.com/mihaifm/linq/releases/latest) archive.
+# Repository
 
-Load it via `<script type="module">`:
+https://github.com/huoshan12345/linqx
 
-```html
-<script type="module" src="./linq.min.js"></script>
-<script type="module">
-    import Enumerable from './linq.min.js'
-    Enumerable.from([1, 2, 3]).forEach(x => console.log(x))
-</script>
-```
+---
 
-You can also load the library via a CDN:
+# Credits
 
-|        CDN | URL                                        |
-| ---------: | :----------------------------------------- |
-| unpkg      | <https://unpkg.com/linq/>                  |
-| jsDelivr   | <https://jsdelivr.com/package/npm/linq>    |
-| packd      | <https://bundle.run/linq@latest?name=linq> |
+Based on the original work by Yoshifumi Kawai and later linq maintainers.
 
-# Credits
+Independent community fork.
 
-[Yoshifumi Kawai](https://github.com/neuecc) developed the [original version](https://github.com/neuecc/linq.js/) of this library.
+---
 
 # License
 
-[MIT License](https://github.com/mihaifm/linq/blob/master/LICENSE)
+MIT

package/dist/core/dictionary.d.ts

@@ -0,0 +1,14 @@
+import type { IDictionary, IEnumerable, KeyValuePair } from '../types.js';
+export declare class Dictionary<TKey, TValue> implements IDictionary<TKey, TValue> {
+    private readonly compareSelector;
+    private readonly entries;
+    constructor(compareSelector?: (key: TKey) => unknown);
+    add(key: TKey, value: TValue): void;
+    get(key: TKey): TValue;
+    set(key: TKey, value: TValue): boolean;
+    contains(key: TKey): boolean;
+    clear(): void;
+    remove(key: TKey): void;
+    count(): number;
+    toEnumerable(): IEnumerable<KeyValuePair<TKey, TValue>>;
+}

package/dist/core/enumerable.d.ts

@@ -0,0 +1,9 @@
+import type { IEnumerable, IEnumerator } from '../types.js';
+export declare class EnumerableSequence<T> implements Iterable<T> {
+    private readonly iteratorFactory;
+    constructor(iteratorFactory: () => Iterator<T>);
+    [Symbol.iterator](): Iterator<T>;
+    getEnumerator(): IEnumerator<T>;
+}
+export interface EnumerableSequence<T> extends IEnumerable<T> {
+}

package/dist/core/enumerator.d.ts

@@ -0,0 +1,10 @@
+import type { IEnumerator } from '../types.js';
+export declare class Enumerator<T> implements IEnumerator<T> {
+    private readonly iterator;
+    private value;
+    private done;
+    constructor(iterator: Iterator<T>);
+    current(): T;
+    moveNext(): boolean;
+    dispose(): void;
+}

package/dist/core/grouping.d.ts

@@ -0,0 +1,11 @@
+import { EnumerableSequence } from './enumerable.js';
+import type { IGrouping } from '../types.js';
+export declare class Grouping<TKey, TElement> extends EnumerableSequence<TElement> {
+    private readonly groupKey;
+    private readonly source;
+    constructor(groupKey: TKey, source: TElement[]);
+    key(): TKey;
+    getSource(): TElement[];
+}
+export interface Grouping<TKey, TElement> extends IGrouping<TKey, TElement> {
+}

package/dist/core/lookup.d.ts

@@ -0,0 +1,12 @@
+import type { IEnumerable, ILookup } from '../types.js';
+import { Grouping } from './grouping.js';
+export declare class Lookup<TKey, TElement> implements ILookup<TKey, TElement> {
+    private readonly compareSelector;
+    private readonly entries;
+    constructor(compareSelector?: (key: TKey) => unknown);
+    add(key: TKey, element: TElement): void;
+    count(): number;
+    get(key: TKey): IEnumerable<TElement>;
+    contains(key: TKey): boolean;
+    toEnumerable(): IEnumerable<Grouping<TKey, TElement>>;
+}

package/dist/core/memoized-enumerable.d.ts

@@ -0,0 +1,12 @@
+import type { IDisposableEnumerable } from '../types.js';
+import { EnumerableSequence } from './enumerable.js';
+export declare class MemoizedEnumerable<T> extends EnumerableSequence<T> {
+    private readonly sourceIterator;
+    private readonly cache;
+    private completed;
+    constructor(source: Iterable<T>);
+    private nextAt;
+    dispose(): void;
+}
+export interface MemoizedEnumerable<T> extends IDisposableEnumerable<T> {
+}

package/dist/core/ordered-enumerable.d.ts

@@ -0,0 +1,14 @@
+import type { Comparer, IOrderedEnumerable } from '../types.js';
+import { EnumerableSequence } from './enumerable.js';
+export interface SortCriterion<T> {
+    keySelector: (element: T) => unknown;
+    comparer: Comparer<unknown>;
+    descending: boolean;
+}
+export declare class OrderedEnumerable<T> extends EnumerableSequence<T> {
+    readonly source: Iterable<T>;
+    readonly criteria: readonly SortCriterion<T>[];
+    constructor(source: Iterable<T>, criteria: readonly SortCriterion<T>[]);
+}
+export interface OrderedEnumerable<T> extends IOrderedEnumerable<T> {
+}

package/dist/core/shared-enumerable.d.ts

@@ -0,0 +1,10 @@
+import type { IDisposableEnumerable } from '../types.js';
+import { EnumerableSequence } from './enumerable.js';
+export declare class SharedEnumerable<T> extends EnumerableSequence<T> {
+    private readonly sourceIterator;
+    private disposed;
+    constructor(source: Iterable<T>);
+    dispose(): void;
+}
+export interface SharedEnumerable<T> extends IDisposableEnumerable<T> {
+}

package/dist/extensions.d.ts

@@ -0,0 +1,18 @@
+import { Enumerable } from '.';
+declare global {
+    interface Map<K, V> {
+        asEnumerable(): Enumerable.IEnumerable<[K, V]>;
+    }
+    interface Array<T> {
+        asEnumerable(): Enumerable.IEnumerable<T>;
+    }
+    interface NamedNodeMap {
+        asEnumerable(): Enumerable.IEnumerable<Attr>;
+    }
+    interface NodeList {
+        asEnumerable(): Enumerable.IEnumerable<Node>;
+    }
+    interface HTMLCollection {
+        asEnumerable(): Enumerable.IEnumerable<Element>;
+    }
+}

package/dist/extensions.js

@@ -0,0 +1,13 @@
+import { n as e, t } from "./src-D_Mk3oMP.js";
+e(Array.prototype, "asEnumerable", function() {
+	return t.from(this);
+}), e(Map.prototype, "asEnumerable", function() {
+	return t.from(this);
+}), typeof document < "u" && (e(NamedNodeMap.prototype, "asEnumerable", function() {
+	return t.from(this);
+}), e(NodeList.prototype, "asEnumerable", function() {
+	return t.from(this);
+}), e(HTMLCollection.prototype, "asEnumerable", function() {
+	return t.from(this);
+}));
+//#endregion

package/dist/factories/choice.d.ts

@@ -0,0 +1,8 @@
+import type { IEnumerable } from '../types.js';
+/**
+ * Creates a sequence that randomly selects from a fixed set with replacement.
+ *
+ * @param values The candidate values.
+ * @returns An infinite deferred sequence, or an empty sequence when no values are supplied.
+ */
+export declare function choice<T>(...values: T[]): IEnumerable<T>;

package/dist/factories/cycle.d.ts

@@ -0,0 +1,8 @@
+import type { IEnumerable } from '../types.js';
+/**
+ * Creates a sequence that repeatedly emits a fixed set of values in order.
+ *
+ * @param values The values in each cycle.
+ * @returns An infinite deferred sequence, or an empty sequence when no values are supplied.
+ */
+export declare function cycle<T>(...values: T[]): IEnumerable<T>;

package/dist/factories/defer.d.ts

@@ -0,0 +1,8 @@
+import type { IEnumerable } from '../types.js';
+/**
+ * Defers creation of a sequence until enumeration begins.
+ *
+ * @param factory Creates the sequence used by each enumeration.
+ * @returns A deferred sequence that invokes `factory` once per enumeration.
+ */
+export declare function defer<T>(factory: () => IEnumerable<T>): IEnumerable<T>;

package/dist/factories/empty.d.ts

@@ -0,0 +1,3 @@
+import type { IEnumerable } from '../types.js';
+/** @returns A reusable sequence containing no elements. */
+export declare function empty<T>(): IEnumerable<T>;

package/dist/factories/from.d.ts

@@ -0,0 +1,46 @@
+import type { IEnumerable } from '../types.js';
+/** @returns An empty sequence. */
+export declare function from(): IEnumerable<unknown>;
+/**
+ * Wraps a number as a single-element sequence.
+ *
+ * @param source The number to wrap.
+ * @returns A sequence containing `source`.
+ */
+export declare function from(source: number): IEnumerable<number>;
+/**
+ * Wraps a boolean as a single-element sequence.
+ *
+ * @param source The boolean to wrap.
+ * @returns A sequence containing `source`.
+ */
+export declare function from(source: boolean): IEnumerable<boolean>;
+/**
+ * Enumerates the characters in a string.
+ *
+ * @param source The string to enumerate.
+ * @returns A reusable sequence of Unicode code-point strings.
+ */
+export declare function from(source: string): IEnumerable<string>;
+/**
+ * Converts an iterable, iterator, array-like object, or source factory to a linqx sequence.
+ *
+ * A source factory is called once per enumeration. A bare iterator is forward-only and is not
+ * reset between enumerations.
+ *
+ * @param source The source to adapt or a function that creates one.
+ * @returns A sequence over the source values.
+ */
+export declare function from<T>(source: Iterable<T> | Iterator<T> | ArrayLike<T> | (() => Iterable<T> | Iterator<T>)): IEnumerable<T>;
+/**
+ * Enumerates an object's own enumerable string-keyed, non-function properties.
+ *
+ * @param source The object whose properties will be enumerated.
+ * @returns A deferred sequence of key-value entries.
+ */
+export declare function from<TKey extends PropertyKey, TValue>(source: Record<TKey, TValue>): IEnumerable<{
+    /** The property's key. */
+    key: TKey;
+    /** The property's value. */
+    value: TValue;
+}>;

package/dist/factories/generate.d.ts

@@ -0,0 +1,9 @@
+import type { IEnumerable } from '../types.js';
+/**
+ * Generates elements by repeatedly invoking a function.
+ *
+ * @param func Produces the next element.
+ * @param count The number of elements to produce. Omit it for an infinite sequence.
+ * @returns A deferred generated sequence.
+ */
+export declare function generate<T>(func: () => T, count?: number): IEnumerable<T>;

package/dist/factories/make.d.ts

@@ -0,0 +1,8 @@
+import type { IEnumerable } from '../types.js';
+/**
+ * Creates a sequence containing exactly one element.
+ *
+ * @param element The element to contain.
+ * @returns A reusable single-element sequence.
+ */
+export declare function make<T>(element: T): IEnumerable<T>;

package/dist/factories/matches.d.ts

@@ -0,0 +1,14 @@
+import type { IEnumerable } from '../types.js';
+/**
+ * Enumerates every regular-expression match in a string.
+ *
+ * A cloned expression is made global automatically, so the supplied `RegExp.lastIndex` is not
+ * read or modified.
+ *
+ * @param input The string to search.
+ * @param pattern A regular expression or pattern string.
+ * @param flags Flags used only when `pattern` is a string; `g` is added when absent.
+ * @returns A deferred sequence of regular-expression match arrays.
+ * @throws {SyntaxError} When a pattern string or its flags are invalid.
+ */
+export declare function matches<T extends RegExpMatchArray = RegExpMatchArray>(input: string, pattern: RegExp | string, flags?: string): IEnumerable<T>;

package/dist/factories/range-down.d.ts

@@ -0,0 +1,10 @@
+import type { IEnumerable } from '../types.js';
+/**
+ * Creates a counted descending arithmetic sequence.
+ *
+ * @param start The first value.
+ * @param count The number of values; non-positive values produce an empty sequence.
+ * @param step The absolute decrement between consecutive values; defaults to one.
+ * @returns A deferred descending numeric sequence.
+ */
+export declare function rangeDown(start: number, count: number, step?: number): IEnumerable<number>;

package/dist/factories/range-to.d.ts

@@ -0,0 +1,12 @@
+import type { IEnumerable } from '../types.js';
+/**
+ * Creates an arithmetic sequence between two inclusive endpoints.
+ *
+ * The direction is inferred from the endpoints and the absolute value of `step` is used.
+ *
+ * @param start The first value.
+ * @param to The inclusive endpoint.
+ * @param step The non-zero distance between consecutive values; defaults to one.
+ * @returns A deferred numeric sequence.
+ */
+export declare function rangeTo(start: number, to: number, step?: number): IEnumerable<number>;

package/dist/factories/range.d.ts

@@ -0,0 +1,10 @@
+import type { IEnumerable } from '../types.js';
+/**
+ * Creates a counted arithmetic sequence.
+ *
+ * @param start The first value.
+ * @param count The number of values; non-positive values produce an empty sequence.
+ * @param step The difference between consecutive values; defaults to one.
+ * @returns A deferred numeric sequence.
+ */
+export declare function range(start: number, count: number, step?: number): IEnumerable<number>;

package/dist/factories/repeat-with-finalize.d.ts

@@ -0,0 +1,9 @@
+import type { IEnumerable } from '../types.js';
+/**
+ * Initializes one value, repeats it indefinitely, and finalizes it when enumeration stops.
+ *
+ * @param initializer Creates the value once per enumeration.
+ * @param finalizer Releases the value after completion, failure, or early termination.
+ * @returns An infinite deferred sequence with deterministic finalization.
+ */
+export declare function repeatWithFinalize<T>(initializer: () => T, finalizer: (element: T) => void): IEnumerable<T>;

package/dist/factories/repeat.d.ts

@@ -0,0 +1,9 @@
+import type { IEnumerable } from '../types.js';
+/**
+ * Repeats one element.
+ *
+ * @param element The value to repeat.
+ * @param count The number of repetitions. Omit it for an infinite sequence.
+ * @returns A deferred repeated sequence.
+ */
+export declare function repeat<T>(element: T, count?: number): IEnumerable<T>;

package/dist/factories/to-infinity.d.ts

@@ -0,0 +1,9 @@
+import type { IEnumerable } from '../types.js';
+/**
+ * Creates an infinite ascending arithmetic sequence.
+ *
+ * @param start The first value; defaults to zero.
+ * @param step The amount added after each element; defaults to one.
+ * @returns An infinite deferred numeric sequence.
+ */
+export declare function toInfinity(start?: number, step?: number): IEnumerable<number>;