@byloth/core 2.0.0-rc.1 → 2.0.0-rc.10

package/src/models/aggregators/aggregated-iterator.ts

@@ -1,8 +1,8 @@
 import { SmartIterator } from "../iterators/index.js";
-import type { GeneratorFunction } from "../iterators/types.js";
+import type { GeneratorFunction, IteratorLike } from "../iterators/types.js";
 
 import ReducedIterator from "./reduced-iterator.js";
-import type { KeyIteratee, KeyTypeGuardIteratee, KeyReducer } from "./types.js";
+import type { KeyedIteratee, KeyedTypeGuardIteratee, KeyedReducer } from "./types.js";
 
 export default class AggregatedIterator<K extends PropertyKey, T>
 {
@@ -11,58 +11,52 @@ export default class AggregatedIterator<K extends PropertyKey, T>
     public constructor(iterable: Iterable<[K, T]>);
     public constructor(iterator: Iterator<[K, T]>);
     public constructor(generatorFn: GeneratorFunction<[K, T]>);
-    public constructor(argument: Iterable<[K, T]> | Iterator<[K, T]> | GeneratorFunction<[K, T]>);
-    public constructor(argument: Iterable<[K, T]> | Iterator<[K, T]> | GeneratorFunction<[K, T]>)
+    public constructor(argument: IteratorLike<[K, T]> | GeneratorFunction<[K, T]>);
+    public constructor(argument: IteratorLike<[K, T]> | GeneratorFunction<[K, T]>)
     {
         this._elements = new SmartIterator(argument);
     }
 
-    public every(predicate: KeyIteratee<K, T, boolean>): ReducedIterator<K, boolean>
+    public every(predicate: KeyedIteratee<K, T, boolean>): ReducedIterator<K, boolean>
     {
-        const indexes = new Map<K, [number, boolean]>();
+        const values = new Map<K, [number, boolean]>();
 
         for (const [key, element] of this._elements)
         {
-            const [index, result] = indexes.get(key) ?? [0, true];
+            const [index, result] = values.get(key) ?? [0, true];
 
             if (!(result)) { continue; }
 
-            indexes.set(key, [index + 1, predicate(key, element, index)]);
+            values.set(key, [index + 1, predicate(key, element, index)]);
         }
 
         return new ReducedIterator(function* ()
         {
-            for (const [key, [_, result]] of indexes)
-            {
-                yield [key, result];
-            }
+            for (const [key, [_, result]] of values) { yield [key, result]; }
         });
     }
-    public some(predicate: KeyIteratee<K, T, boolean>): ReducedIterator<K, boolean>
+    public some(predicate: KeyedIteratee<K, T, boolean>): ReducedIterator<K, boolean>
     {
-        const indexes = new Map<K, [number, boolean]>();
+        const values = new Map<K, [number, boolean]>();
 
         for (const [key, element] of this._elements)
         {
-            const [index, result] = indexes.get(key) ?? [0, false];
+            const [index, result] = values.get(key) ?? [0, false];
 
             if (result) { continue; }
 
-            indexes.set(key, [index + 1, predicate(key, element, index)]);
+            values.set(key, [index + 1, predicate(key, element, index)]);
         }
 
         return new ReducedIterator(function* ()
         {
-            for (const [key, [_, result]] of indexes)
-            {
-                yield [key, result];
-            }
+            for (const [key, [_, result]] of values) { yield [key, result]; }
         });
     }
 
-    public filter(predicate: KeyIteratee<K, T, boolean>): AggregatedIterator<K, T>;
-    public filter<S extends T>(predicate: KeyTypeGuardIteratee<K, T, S>): AggregatedIterator<K, S>;
-    public filter(predicate: KeyIteratee<K, T, boolean>): AggregatedIterator<K, T>
+    public filter(predicate: KeyedIteratee<K, T, boolean>): AggregatedIterator<K, T>;
+    public filter<S extends T>(predicate: KeyedTypeGuardIteratee<K, T, S>): AggregatedIterator<K, S>;
+    public filter(predicate: KeyedIteratee<K, T, boolean>): AggregatedIterator<K, T>
     {
         const elements = this._elements;
 
@@ -74,13 +68,13 @@ export default class AggregatedIterator<K extends PropertyKey, T>
             {
                 const index = indexes.get(key) ?? 0;
 
-                indexes.set(key, index + 1);
-
                 if (predicate(key, element, index)) { yield [key, element]; }
+
+                indexes.set(key, index + 1);
             }
         });
     }
-    public map<V>(iteratee: KeyIteratee<K, T, V>): AggregatedIterator<K, V>
+    public map<V>(iteratee: KeyedIteratee<K, T, V>): AggregatedIterator<K, V>
     {
         const elements = this._elements;
 
@@ -92,29 +86,24 @@ export default class AggregatedIterator<K extends PropertyKey, T>
             {
                 const index = indexes.get(key) ?? 0;
 
-                indexes.set(key, index + 1);
-
                 yield [key, iteratee(key, element, index)];
+
+                indexes.set(key, index + 1);
             }
         });
     }
-    public reduce(reducer: KeyReducer<K, T, T>): ReducedIterator<K, T>;
-    public reduce<A>(reducer: KeyReducer<K, T, A>, initialValue: (key: K) => A): ReducedIterator<K, A>;
-    public reduce<A>(reducer: KeyReducer<K, T, A>, initialValue?: (key: K) => A): ReducedIterator<K, A>
+    public reduce(reducer: KeyedReducer<K, T, T>): ReducedIterator<K, T>;
+    public reduce<A>(reducer: KeyedReducer<K, T, A>, initialValue: (key: K) => A): ReducedIterator<K, A>;
+    public reduce<A>(reducer: KeyedReducer<K, T, A>, initialValue?: (key: K) => A): ReducedIterator<K, A>
     {
-        const accumulators = new Map<K, [number, A]>();
+        const values = new Map<K, [number, A]>();
 
         for (const [key, element] of this._elements)
         {
             let index: number;
             let accumulator: A;
 
-            if (accumulators.has(key))
-            {
-                [index, accumulator] = accumulators.get(key)!;
-
-                index += 1;
-            }
+            if (values.has(key)) { [index, accumulator] = values.get(key)!; }
             else if (initialValue !== undefined)
             {
                 index = 0;
@@ -122,103 +111,161 @@ export default class AggregatedIterator<K extends PropertyKey, T>
             }
             else
             {
-                accumulators.set(key, [0, (element as unknown) as A]);
+                values.set(key, [0, (element as unknown) as A]);
 
                 continue;
             }
 
-            accumulator = reducer(key, accumulator, element, index);
-
-            accumulators.set(key, [index, accumulator]);
+            values.set(key, [index + 1, reducer(key, accumulator, element, index)]);
         }
 
         return new ReducedIterator(function* ()
         {
-            for (const [key, [_, accumulator]] of accumulators)
-            {
-                yield [key, accumulator];
-            }
+            for (const [key, [_, accumulator]] of values) { yield [key, accumulator]; }
         });
     }
 
-    public unique(): AggregatedIterator<K, T>
+    public flatMap<V>(iteratee: KeyedIteratee<K, T, Iterable<V>>): AggregatedIterator<K, V>
     {
         const elements = this._elements;
 
         return new AggregatedIterator(function* ()
         {
-            const keys = new Map<K, Set<T>>();
+            const indexes = new Map<K, number>();
 
             for (const [key, element] of elements)
             {
-                const values = keys.get(key) ?? new Set<T>();
-
-                if (values.has(element)) { continue; }
+                const index = indexes.get(key) ?? 0;
+                const values = iteratee(key, element, index);
 
-                values.add(element);
-                keys.set(key, values);
+                for (const value of values) { yield [key, value]; }
 
-                yield [key, element];
+                indexes.set(key, index + 1);
             }
         });
     }
 
-    public count(): ReducedIterator<K, number>
+    public drop(count: number): AggregatedIterator<K, T>
     {
-        const counters = new Map<K, number>();
+        const elements = this._elements;
 
-        for (const [key] of this._elements)
+        return new AggregatedIterator(function* ()
         {
-            const count = counters.get(key) ?? 0;
+            const indexes = new Map<K, number>();
 
-            counters.set(key, count + 1);
-        }
+            for (const [key, element] of elements)
+            {
+                const index = indexes.get(key) ?? 0;
+                if (index < count)
+                {
+                    indexes.set(key, index + 1);
 
-        return new ReducedIterator(function* ()
+                    continue;
+                }
+
+                yield [key, element];
+            }
+        });
+    }
+    public take(limit: number): AggregatedIterator<K, T>
+    {
+        const elements = this._elements;
+
+        return new AggregatedIterator(function* ()
         {
-            for (const [key, count] of counters)
+            const indexes = new Map<K, number>();
+
+            for (const [key, element] of elements)
             {
-                yield [key, count];
+                const index = indexes.get(key) ?? 0;
+                if (index >= limit) { continue; }
+
+                yield [key, element];
+
+                indexes.set(key, index + 1);
             }
         });
     }
-    public first(): ReducedIterator<K, T>
+
+    public find(predicate: KeyedIteratee<K, T, boolean>): ReducedIterator<K, T | undefined>;
+    public find<S extends T>(predicate: KeyedTypeGuardIteratee<K, T, S>): ReducedIterator<K, S | undefined>;
+    public find(predicate: KeyedIteratee<K, T, boolean>): ReducedIterator<K, T | undefined>
     {
-        const firsts = new Map<K, T>();
+        const values = new Map<K, [number, T | undefined]>();
 
         for (const [key, element] of this._elements)
         {
-            if (firsts.has(key)) { continue; }
+            let [index, finding] = values.get(key) ?? [0, undefined];
 
-            firsts.set(key, element);
+            if (finding !== undefined) { continue; }
+            if (predicate(key, element, index)) { finding = element; }
+
+            values.set(key, [index + 1, finding]);
         }
 
         return new ReducedIterator(function* ()
         {
-            for (const [key, element] of firsts)
+            for (const [key, [_, finding]] of values) { yield [key, finding]; }
+        });
+    }
+
+    public enumerate(): AggregatedIterator<K, [number, T]>
+    {
+        return this.map((_, value, index) => [index, value]);
+    }
+    public unique(): AggregatedIterator<K, T>
+    {
+        const elements = this._elements;
+
+        return new AggregatedIterator(function* ()
+        {
+            const keys = new Map<K, Set<T>>();
+
+            for (const [key, element] of elements)
             {
+                const values = keys.get(key) ?? new Set<T>();
+
+                if (values.has(element)) { continue; }
+
+                values.add(element);
+                keys.set(key, values);
+
                 yield [key, element];
             }
         });
     }
-    public last(): ReducedIterator<K, T>
+
+    public count(): ReducedIterator<K, number>
     {
-        const lasts = new Map<K, T>();
+        const counters = new Map<K, number>();
 
-        for (const [key, element] of this._elements)
+        for (const [key] of this._elements)
         {
-            lasts.set(key, element);
+            const count = counters.get(key) ?? 0;
+
+            counters.set(key, count + 1);
         }
 
         return new ReducedIterator(function* ()
         {
-            for (const [key, element] of lasts)
-            {
-                yield [key, element];
-            }
+            for (const [key, count] of counters) { yield [key, count]; }
         });
     }
 
+    public forEach(iteratee: KeyedIteratee<K, T>): void
+    {
+        const indexes = new Map<K, number>();
+
+        for (const [key, element] of this._elements)
+        {
+            const index = indexes.get(key) ?? 0;
+
+            iteratee(key, element, index);
+
+            indexes.set(key, index + 1);
+        }
+    }
+
     public keys(): SmartIterator<K>
     {
         const elements = this._elements;
@@ -246,16 +293,15 @@ export default class AggregatedIterator<K extends PropertyKey, T>
 
         return new SmartIterator<T>(function* ()
         {
-            for (const [_, element] of elements)
-            {
-                yield element;
-            }
+            for (const [_, element] of elements) { yield element; }
         });
     }
 
     public toArray(): T[][]
     {
-        return Array.from(this.toMap().values());
+        const map = this.toMap();
+
+        return Array.from(map.values());
     }
     public toMap(): Map<K, T[]>
     {
@@ -286,5 +332,5 @@ export default class AggregatedIterator<K extends PropertyKey, T>
         return groups;
     }
 
-    public get [Symbol.toStringTag]() { return "AggregatedIterator"; }
+    public readonly [Symbol.toStringTag]: string = "AggregatedIterator";
 }

package/src/models/aggregators/index.ts

@@ -1,7 +1,5 @@
-import Aggregator from "./aggregator.js";
-import AsyncAggregator from "./async-aggregator.js";
 import AggregatedIterator from "./aggregated-iterator.js";
 import AggregatedAsyncIterator from "./aggregated-async-iterator.js";
 import ReducedIterator from "./reduced-iterator.js";
 
-export { Aggregator, AsyncAggregator, AggregatedIterator, AggregatedAsyncIterator, ReducedIterator };
+export { AggregatedIterator, AggregatedAsyncIterator, ReducedIterator };

package/src/models/aggregators/reduced-iterator.ts

@@ -2,7 +2,8 @@ import { ValueException } from "../exceptions/index.js";
 import { SmartIterator } from "../iterators/index.js";
 import type { GeneratorFunction } from "../iterators/types.js";
 
-import type { KeyIteratee, KeyReducer, KeyTypeGuardIteratee } from "./types.js";
+import AggregatedIterator from "./aggregated-iterator.js";
+import type { KeyedIteratee, KeyedReducer, KeyedTypeGuardIteratee } from "./types.js";
 
 export default class ReducedIterator<K extends PropertyKey, T>
 {
@@ -17,56 +18,64 @@ export default class ReducedIterator<K extends PropertyKey, T>
         this._elements = new SmartIterator(argument);
     }
 
-    public filter(predicate: KeyIteratee<K, T, boolean>): ReducedIterator<K, T>;
-    public filter<S extends T>(predicate: KeyTypeGuardIteratee<K, T, S>): ReducedIterator<K, S>;
-    public filter(predicate: KeyIteratee<K, T, boolean>): ReducedIterator<K, T>
+    public every(predicate: KeyedIteratee<K, T, boolean>): boolean
     {
-        const elements = this._elements;
+        for (const [index, [key, element]] of this._elements.enumerate())
+        {
+            if (!(predicate(key, element, index))) { return false; }
+        }
+
+        return true;
+    }
+    public some(predicate: KeyedIteratee<K, T, boolean>): boolean
+    {
+        for (const [index, [key, element]] of this._elements.enumerate())
+        {
+            if (predicate(key, element, index)) { return true; }
+        }
+
+        return false;
+    }
+
+    public filter(predicate: KeyedIteratee<K, T, boolean>): ReducedIterator<K, T>;
+    public filter<S extends T>(predicate: KeyedTypeGuardIteratee<K, T, S>): ReducedIterator<K, S>;
+    public filter(predicate: KeyedIteratee<K, T, boolean>): ReducedIterator<K, T>
+    {
+        const elements = this._elements.enumerate();
 
         return new ReducedIterator(function* ()
         {
-            for (const [index, [key, element]] of elements.enumerate())
+            for (const [index, [key, element]] of elements)
             {
-                if (predicate(key, element, index))
-                {
-                    yield [key, element];
-                }
+                if (predicate(key, element, index)) { yield [key, element]; }
             }
         });
     }
-    public map<V>(iteratee: KeyIteratee<K, T, V>): ReducedIterator<K, V>
+    public map<V>(iteratee: KeyedIteratee<K, T, V>): ReducedIterator<K, V>
     {
-        const elements = this._elements;
+        const elements = this._elements.enumerate();
 
         return new ReducedIterator(function* ()
         {
-            for (const [index, [key, element]] of elements.enumerate())
+            for (const [index, [key, element]] of elements)
             {
                 yield [key, iteratee(key, element, index)];
             }
         });
     }
-    public reduce(reducer: KeyReducer<K, T, T>): T;
-    public reduce<A>(reducer: KeyReducer<K, T, A>, initialValue: A): A;
-    public reduce<A>(reducer: KeyReducer<K, T, A>, initialValue?: A): A
+    public reduce(reducer: KeyedReducer<K, T, T>): T;
+    public reduce<A>(reducer: KeyedReducer<K, T, A>, initialValue: A): A;
+    public reduce<A>(reducer: KeyedReducer<K, T, A>, initialValue?: A): A
     {
         let index = 0;
-        let accumulator: A;
-
-        if (initialValue !== undefined)
+        let accumulator = initialValue;
+        if (accumulator === undefined)
         {
-            accumulator = initialValue;
-        }
-        else
-        {
-            const firstElement = this._elements.next();
-            if (firstElement.done)
-            {
-                throw new ValueException("Cannot reduce an empty iterator without an initial value.");
-            }
+            const result = this._elements.next();
+            if (result.done) { throw new ValueException("Cannot reduce an empty iterator without an initial value."); }
 
+            accumulator = (result.value[1] as unknown) as A;
             index += 1;
-            accumulator = (firstElement.value[1] as unknown) as A;
         }
 
         for (const [key, element] of this._elements)
@@ -79,6 +88,85 @@ export default class ReducedIterator<K extends PropertyKey, T>
         return accumulator;
     }
 
+    public flatMap<V>(iteratee: KeyedIteratee<K, T, Iterable<V>>): AggregatedIterator<K, V>
+    {
+        const elements = this._elements.enumerate();
+
+        return new AggregatedIterator(function* ()
+        {
+            for (const [index, [key, element]] of elements)
+            {
+                for (const value of iteratee(key, element, index)) { yield [key, value]; }
+            }
+        });
+    }
+
+    public drop(count: number): ReducedIterator<K, T>
+    {
+        const elements = this._elements.enumerate();
+
+        return new ReducedIterator(function* ()
+        {
+            for (const [index, [key, element]] of elements)
+            {
+                if (index >= count) { yield [key, element]; }
+            }
+        });
+    }
+    public take(count: number): ReducedIterator<K, T>
+    {
+        const elements = this._elements.enumerate();
+
+        return new ReducedIterator(function* ()
+        {
+            for (const [index, [key, element]] of elements)
+            {
+                if (index >= count) { break; }
+
+                yield [key, element];
+            }
+        });
+    }
+
+    public enumerate(): ReducedIterator<K, [number, T]>
+    {
+        return this.map((_, element, index) => [index, element]);
+    }
+    public unique(): ReducedIterator<K, T>
+    {
+        const elements = this._elements;
+
+        return new ReducedIterator(function* ()
+        {
+            const values = new Set<T>();
+
+            for (const [key, element] of elements)
+            {
+                if (values.has(element)) { continue; }
+                values.add(element);
+
+                yield [key, element];
+            }
+        });
+    }
+
+    public count(): number
+    {
+        let index = 0;
+
+        for (const _ of this._elements) { index += 1; }
+
+        return index;
+    }
+
+    public forEach(iteratee: KeyedIteratee<K, T>): void
+    {
+        for (const [index, [key, element]] of this._elements.enumerate())
+        {
+            iteratee(key, element, index);
+        }
+    }
+
     public keys(): SmartIterator<K>
     {
         const elements = this._elements;
@@ -121,5 +209,5 @@ export default class ReducedIterator<K extends PropertyKey, T>
         return Object.fromEntries(this.items()) as Record<K, T>;
     }
 
-    public get [Symbol.toStringTag]() { return "ReducedIterator"; }
+    public readonly [Symbol.toStringTag]: string = "ReducedIterator";
 }

package/src/models/aggregators/types.ts

@@ -1,14 +1,19 @@
+/* eslint-disable max-len */
+
 import type { MaybePromise } from "../promises/types.js";
 
-export type KeyIteratee<K extends PropertyKey, T, R = void> = (key: K, value: T, index: number) => R;
-export type MaybeAsyncKeyIteratee<K extends PropertyKey, T, R = void> = (key: K, value: T, index: number) =>
-    MaybePromise<R>;
+export type KeyedIteratee<K extends PropertyKey, T, R = void> = (key: K, value: T, index: number) => R;
+export type AsyncKeyedIteratee<K extends PropertyKey, T, R = void> = (key: K, value: T, index: number) => Promise<R>;
+export type MaybeAsyncKeyedIteratee<K extends PropertyKey, T, R = void> = (key: K, value: T, index: number) => MaybePromise<R>;
+
+export type KeyedTypeGuardIteratee<K extends PropertyKey, T, R extends T> = (key: K, value: T, index: number) => value is R;
+
+// @ts-expect-error - This is an asyncronous type guard keyed-iteratee that guarantees the return value is a promise.
+export type AsyncKeyedTypeGuardIteratee<K extends PropertyKey, T, R extends T> = (key: K, value: T, index: number) => value is Promise<R>;
 
-export type KeyTypeGuardIteratee<K extends PropertyKey, T, R extends T> =
-    (key: K, value: T, index: number) => value is R;
-export type MaybeAsyncKeyTypeGuardIteratee<K extends PropertyKey, T, R extends T> =
-    (key: K, value: MaybePromise<T>, index: number) => value is Awaited<R>;
+// @ts-expect-error - This may be an asyncronous type guard keyed-iteratee that guarantees the return value may be a promise.
+export type MaybeAsyncKeyedTypeGuardIteratee<K extends PropertyKey, T, R extends T> = (key: K, value: T, index: number) => value is MaybePromise<R>;
 
-export type KeyReducer<K extends PropertyKey, T, A> = (key: K, accumulator: A, value: T, index: number) => A;
-export type MaybeAsyncKeyReducer<K extends PropertyKey, T, A> =
-    (key: K, accumulator: A, value: T, index: number) => MaybePromise<A>;
+export type KeyedReducer<K extends PropertyKey, T, A> = (key: K, accumulator: A, value: T, index: number) => A;
+export type AsyncKeyedReducer<K extends PropertyKey, T, A> = (key: K, accumulator: A, value: T, index: number) => Promise<A>;
+export type MaybeAsyncKeyedReducer<K extends PropertyKey, T, A> = (key: K, accumulator: A, value: T, index: number) => MaybePromise<A>;

package/src/models/callbacks/callable-object.ts

@@ -0,0 +1,23 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import type { Callback } from "./types.js";
+
+export const SmartFunction = (Function as unknown) as
+    new<T extends Callback<any[], any> = () => void>(...args: string[]) =>
+        (...args: Parameters<T>) => ReturnType<T>;
+
+export default abstract class CallableObject<T extends Callback<any[], any> = () => void>
+    extends SmartFunction<T>
+{
+    public constructor()
+    {
+        super(`return this.invoke(...arguments);`);
+
+        const self = this.bind(this);
+        Object.setPrototypeOf(this, self);
+
+        return self as this;
+    }
+
+    public abstract invoke(...args: Parameters<T>): ReturnType<T>;
+}

package/src/models/callbacks/index.ts

@@ -0,0 +1,5 @@
+import CallableObject, { SmartFunction } from "./callable-object.js";
+import Publisher from "./publisher.js";
+import SwitchableCallback from "./switchable-callback.js";
+
+export { CallableObject, Publisher, SmartFunction, SwitchableCallback };

package/src/models/callbacks/publisher.ts

@@ -0,0 +1,45 @@
+import { ReferenceException } from "../exceptions/index.js";
+
+import type { Callback } from "./types.js";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default class Publisher<T extends { [K in keyof T]: Callback<any[], any> } = Record<string, Callback>>
+{
+    protected _subscribers: Map<keyof T, Callback<unknown[], unknown>[]>;
+
+    public constructor()
+    {
+        this._subscribers = new Map();
+    }
+
+    public subscribe<K extends keyof T>(event: K, subscriber: T[K]): () => void
+    {
+        if (!(this._subscribers.has(event))) { this._subscribers.set(event, []); }
+
+        const subscribers = this._subscribers.get(event)!;
+        subscribers.push(subscriber);
+
+        return () =>
+        {
+            const index = subscribers.indexOf(subscriber);
+            if (index < 0)
+            {
+                throw new ReferenceException("Unable to unsubscribe the required subscriber. " +
+                    "The subscription was already unsubscribed.");
+            }
+
+            subscribers.splice(index, 1);
+        };
+    }
+
+    public publish<K extends keyof T>(event: K, ...args: Parameters<T[K]>): ReturnType<T[K]>[]
+    {
+        const subscribers = this._subscribers.get(event);
+        if (!(subscribers)) { return []; }
+
+        return subscribers.slice()
+            .map((subscriber) => subscriber(...args)) as ReturnType<T[K]>[];
+    }
+
+    public readonly [Symbol.toStringTag]: string = "Publisher";
+}