@typedly/collection 2.0.0 → 4.0.0

package/README.md

@@ -29,6 +29,7 @@ A **TypeScript** type definitions package for data collections with customizable
 - [Api](#api)
   - Interface
     - [`CollectionAdapter`](#collectionadapter)
+    - [`CollectionAdapterConstructor`](#collectionadapterconstructor)
     - [`CollectionShape`](#collectionshape)
   - Type
     - [`CollectionConstructor`](#collectionconstructor)
@@ -52,6 +53,7 @@ npm install @typedly/collection --save-peer
 import {
   // Interface.
   CollectionAdapter,
+  CollectionAdapterConstructor,
   CollectionShape,
   // Type.
   CollectionConstructor
@@ -68,26 +70,137 @@ The adapter interface for collections.
 import { CollectionAdapter } from '@typedly/collection';
 ```
 
+### `CollectionAdapterConstructor`
+
+The interface of adapter constructor.
+
+```typescript
+import { CollectionAdapter, CollectionAdapterConstructor } from '@typedly/collection';
+import { AsyncReturn } from '@typedly/data';
+/**
+ * Example class with fake async returned types.
+ */
+export class ExampleCollectionAdapter<
+  E,
+  T,
+  R extends boolean = false, 
+> implements CollectionAdapter<E, T, R> {
+  public get async(): R {
+    return this.#async;
+  }
+  public get size(): number {
+    return this.#items.length;
+  }
+  public get  value(): T {
+    // Implementation depends on specific requirements.
+    return {} as T;
+  }
+  version = "1.0.0";
+  #async: R;
+  #items: E[] = [];
+  constructor({async}: {async: R}, ...elements: E[]) {
+    this.#async = async;
+    this.#items.push(...elements);
+  }
+  public add(...element: E[]): AsyncReturn<R, this> {
+    this.#items.push(...element);
+    return this as AsyncReturn<R, this>;
+  }
+  public clear(): AsyncReturn<R, this> {
+    this.#items = [];
+    return this as AsyncReturn<R, this>;
+  }
+  public delete(...element: E[]): AsyncReturn<R, boolean> {
+    const index = this.#items.indexOf(element[0]);
+    if (index !== -1) {
+      this.#items.splice(index, 1);
+      return true as AsyncReturn<R, boolean>;
+    }
+    return false as AsyncReturn<R, boolean>;
+  }
+  public destroy(): AsyncReturn<R, this> {
+    this.#items = [];
+    return this as AsyncReturn<R, this>;
+  }
+  public forEach(callbackfn: (element: E, element2: E, collection: CollectionAdapter<E, T, R>) => void, thisArg?: any): AsyncReturn<R, this> {
+    this.#items.forEach((value: E) => {
+      callbackfn.call(thisArg, value, value, this);
+    });
+    return this as AsyncReturn<R, this>;
+  }
+  public getValue(): AsyncReturn<R, T> {
+    // Implementation depends on specific requirements.
+    return {} as AsyncReturn<R, T>;
+  }
+  public has(element: E): AsyncReturn<R, boolean> {
+    return this.#items.includes(element) as AsyncReturn<R, boolean>;
+  }
+  public lock(): this {
+    // Implementation depends on specific requirements.
+    return this;
+  }
+  public setValue(value: T): AsyncReturn<R, this> {
+    // Implementation depends on specific requirements.
+    return this as AsyncReturn<R, this>;
+  }
+  public unlock(): AsyncReturn<R, this> {
+    // Implementation depends on specific requirements.
+    return this as AsyncReturn<R, this>;
+  }
+}
+
+// Create factory function for creating adapter instances.
+function createAdapter<
+  E,
+  T,
+  R extends boolean = false,
+  A extends CollectionAdapter<E, T, R> = CollectionAdapter<E, T, R>
+>(
+  AdapterCtor: CollectionAdapterConstructor<E, T, R, { async: R }, A>,
+  async: R,
+  ...elements: E[]
+): A {
+  return new AdapterCtor({ async }, ...elements);
+}
+
+// ExampleCollectionAdapter<number, unknown, false>
+const adapter1 = createAdapter(ExampleCollectionAdapter, false, 1, 2, 3);
+// ExampleCollectionAdapter<string, unknown, true>
+const adapter2 = createAdapter(ExampleCollectionAdapter, true, 'a', 'b', 'c');
+
+```
+
 ### `CollectionShape`
 
+Represents a collection of elements.
+
 ```typescript
-import { CollectionShape } from '@typedly/collection';
+import { CollectionShape, IterValue } from '@typedly/collection';
+
+// Example class implementing CollectionShape.
+export class AnyCollection<
+  E,
+  T = Set<E>
+> implements CollectionShape<E, T, false> {
+  async = false as false;
 
-export class AnyCollection<T, V = Set<T>> implements CollectionShape<T, V> {
   // Data shape method.
-  get value(): V {
+  get value(): T {
     // Implementation depends on specific requirements.
-    return {} as V;
+    return this.#items;
   }
 
   // Example internal storage.
-  #items: V = new Set<T>() as V;
-
-  constructor(initialItems?: T[], type: new (...args: any[]) => V = Set as any) {
-    this.#items = new type();
-    if (initialItems) {
-      initialItems.forEach(item => (this.#items as any).add(item));
-    }
+  #items: T;
+
+  constructor(
+    { async, value }: { async: false, value?: T },
+    type?: new (...args: any[]) => T,
+    ...elements: E[]
+  ) {
+    this.async = async;
+    this.#items = type ? new type() : value ? value : {} as T;
+    elements.forEach(element => (this.#items as any).add(element));
   }
 
   public clear(): this {
@@ -102,8 +215,13 @@ export class AnyCollection<T, V = Set<T>> implements CollectionShape<T, V> {
     // Implementation depends on specific requirements.
     return this;
   }
-  public set(value: V): this {
+  public getValue(): T {
+    // Implementation depends on specific requirements.
+    return this.#items;
+  }
+  public setValue(value: T): this {
     // Implementation depends on specific requirements.
+    this.#items = value;
     return this;
   }
   public unlock(): this {
@@ -112,22 +230,23 @@ export class AnyCollection<T, V = Set<T>> implements CollectionShape<T, V> {
   }
 
 
-  add(element: T): this {
+  add(element: E): this {
     (this.#items as any).add(element);
     return this;
   }
 
-  delete(element: T): boolean {
+  delete(element: E): boolean {
     return (this.#items as any).delete(element);
   }
 
-  forEach(callbackfn: (element: T, element2: T, collection: CollectionShape<T, V>) => void, thisArg?: any): void {
-    (this.#items as any).forEach((value: T) => {
+  forEach(callbackfn: (element: E, element2: E, collection: CollectionShape<E, T, false>) => void, thisArg?: any): this {
+    (this.#items as any).forEach((value: E) => {
       callbackfn.call(thisArg, value, value, this);
     });
+    return this;
   }
 
-  has(element: T): boolean {
+  has(element: E): boolean {
     return (this.#items as any).has(element);
   }
 
@@ -139,7 +258,7 @@ export class AnyCollection<T, V = Set<T>> implements CollectionShape<T, V> {
     return 'MyCollection';
   }
 
-  [Symbol.iterator](): Iterator<T> {
+  [Symbol.iterator](): IterableIterator<IterValue<T>> {
     return (this.#items as any).values();
   }
 }
@@ -147,10 +266,22 @@ export class AnyCollection<T, V = Set<T>> implements CollectionShape<T, V> {
 const obj1 = {age: 27};
 const obj2 = {age: 37};
 const obj3 = {age: 47};
-const anyCollection = new AnyCollection<{age: number}, WeakSet<{age: number}>>([], WeakSet)
+const anyCollection1 = new AnyCollection<{age: number}, Set<{age: number}>>(
+  { async: false, value: new Set([{age: 27}, {age: 37}, {age: 47}]) }
+  )
   .add(obj1)
   .add(obj2)
   .add(obj3);
+
+console.log(`anyCollection1:`, anyCollection1.value);
+
+const anyCollection2 = new AnyCollection<{age: number}, Set<{age: number}>>(
+  { async: false }, Set)
+  .add(obj1)
+  .add(obj2)
+  .add(obj3);
+
+console.log(`anyCollection2:`, anyCollection2.value);
 ```
 
 ### Type
@@ -172,10 +303,11 @@ If you find this package useful and would like to support its and general develo
 Support via:
 
 - [Stripe](https://donate.stripe.com/dR614hfDZcJE3wAcMM)
-- [Revolut](https://checkout.revolut.com/pay/048b10a3-0e10-42c8-a917-e3e9cb4c8e29)
+- ~~[Revolut](https://checkout.revolut.com/pay/048b10a3-0e10-42c8-a917-e3e9cb4c8e29)~~
 - [GitHub](https://github.com/sponsors/angular-package/sponsorships?sponsor=sciborrudnicki&tier_id=83618)
 - [DonorBox](https://donorbox.org/become-a-sponsor-to-the-angular-package?default_interval=o)
 - [Patreon](https://www.patreon.com/checkout/angularpackage?rid=0&fan_landing=true&view_as=public)
+- [4Fund](https://4fund.com/bruubs)
 
 or via Trust Wallet
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typedly/collection",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "author": "wwwdev.io <dev@wwwdev.io>",
   "description": "A TypeScript type definitions package for data collections with customizable storage.",
   "license": "MIT",
@@ -9,7 +9,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "peerDependencies": {
-    "@typedly/data": "^2.0.0"
+    "@typedly/data": "^4.0.0"
   },
   "repository": {
     "type": "git",

package/types/typedly-collection.d.ts

@@ -1,75 +1,103 @@
-import { DataShape } from '@typedly/data';
+import { DataShape, AsyncReturn } from '@typedly/data';
 import { ConstrainedConstructor } from '@typedly/constructor';
 
 /**
  * @description Represents a collection of elements.
  * @export
  * @interface Collection
- * @template T The type of elements in the collection.
- * @template V The type of the value in the collection, data of elements.
- * @extends {DataShape<V>}
+ * @template E The type of elements in the collection.
+ * @template [T=any] The type of the value in the collection, data of elements.
+ * @template {boolean} [R=false] The `boolean` type to determine async methods.
+ * @extends {DataShape<T, R>}
  */
-interface CollectionShape<T, V = any> extends DataShape<V> {
+interface CollectionShape<E, T = any, R extends boolean = false> extends DataShape<T, R> {
     /**
-     * @description Adds elements to the collection.
-     * @param {...T[]} element Element of type `T` to add.
-     * @returns {this} The collection instance.
-     */
-    add(...element: T[]): this;
-    /**
-     * @description Deletes elements from the collection.
-     * @param {...T[]} element Element of type `T` to delete.
-     * @returns {boolean} `true` if the element was successfully deleted, otherwise `false`.
+     * @description Indicates whether the collection operates in asynchronous mode.
+     * @readonly
+     * @type {R}
      */
-    delete(...element: T[]): boolean;
+    readonly async: R;
     /**
-     * @description Executes a provided function once for each collection element.
-     * @param {(value: T, value2: T, collection: CollectionShape<T, V>) => void} callbackfn Function to execute for each element.
-     * @param {any} [thisArg] Value to use as `this` when executing `callbackfn`.
+     * @description The number of items in the collection.
+     * @returns {number}
      */
-    forEach(callbackfn: (element: T, element2: T, collection: CollectionShape<T, V>) => void, thisArg?: any): void;
+    readonly size: number;
     /**
-     * @description Checks if every item exists in the collection.
-     * @param {...T[]} element Element of type `T` to check for existence.
-     * @returns {boolean} `true` if the element exists, otherwise `false`.
+     * @description Adds elements to the collection.
+     * @param {...E[]} element Element of type `T` to add.
+     * @returns {AsyncReturn<R, this>} The collection instance `this`, or in `Promise`.
      */
-    has(...element: T[]): boolean;
+    add(...element: E[]): AsyncReturn<R, this>;
     /**
-     * @description The number of items in the collection.
-     * @returns {number}
+     * @description Deletes elements from the collection.
+     * @param {...E[]} element Element of type `T` to delete.
+     * @returns {AsyncReturn<R, boolean>} `true` if the element was successfully deleted, otherwise `false`.
      */
-    readonly size: number;
+    delete(...element: E[]): AsyncReturn<R, boolean>;
     /**
-     * @description Returns a tag name for collection.
-     * @returns {string}
+     * @description Executes a provided function once for each collection element.
+     * @param {(value: E, value2: E, collection: CollectionShape<E, T, R>) => void} callbackfn Function to execute for each element.
+     * @param {AsyncReturn<R, this>} [thisArg] Value to use as `this` when executing `callbackfn`.
      */
-    get [Symbol.toStringTag](): string;
+    forEach(callbackfn: (element: E, element2: E, collection: CollectionShape<E, T, R>) => void, thisArg?: any): AsyncReturn<R, this>;
     /**
-     * @description Returns an iterator for the collection.
-     * @returns {Iterator<T>}
+     * @description Checks if every item exists in the collection.
+     * @param {...E[]} element Element of type `T` to check for existence.
+     * @returns {AsyncReturn<R, boolean>} `true` if the element exists, otherwise `false`.
      */
-    [Symbol.iterator](): Iterator<T>;
+    has(...element: E[]): AsyncReturn<R, boolean>;
 }
 
 /**
  * @description The adapter interface for collections.
  * @export
  * @interface CollectionAdapter
- * @template Element  The type of elements in the collection.
- * @template Type The type of the value in the collection, data of elements.
- * @extends {CollectionShape<Element, Type>}
+ * @template E  The type of elements in the collection.
+ * @template T The type of the value in the collection, data of elements.
+ * @template R The `boolean` type to determine async methods.
+ * @extends {CollectionShape<E, T>}
  */
-interface CollectionAdapter<Element, Type> extends CollectionShape<Element, Type> {
+interface CollectionAdapter<E, T, R extends boolean = false> extends CollectionShape<E, T, R> {
     version: string;
 }
 
+/**
+ * @description The interface of adapter constructor.
+ * @export
+ * @interface CollectionAdapterConstructor
+ * @template E Elements type.
+ * @template {boolean} [R=false] The boolean type indicates the async methods.
+ * @template {C} [C={async?: R, value?: T}] The configuration object type for the constructor, which has an `async` property of type `R` and an optional `value` property of type `T`.
+ * @template {CollectionAdapter<E, T, R>} [A=CollectionAdapter<E, T, R>]
+ */
+interface CollectionAdapterConstructor<E, T, R extends boolean = false, C extends {
+    async?: R;
+    value?: T;
+} = {
+    async?: R;
+    value?: T;
+}, A extends CollectionAdapter<E, T, R> = CollectionAdapter<E, T, R>> {
+    new ({ async, value }: C, ...elements: E[]): A;
+}
+
 /**
  * @description The constructor type for CollectionShape.
  * @export
- * @template T The type of the elements in the collection.
- * @template V The type of the value in the collection, data of elements.
- * @template {CollectionShape<T, V>} C
+ * @template E The type of the elements in the collection.
+ * @template T The type of the value in the collection, data of elements.
+ * @template {boolean} [R=false] The `boolean` type to determine async methods.
+ * @template {G} [G={async?: R, value?: T}] The configuration object type for the constructor, which has an `async` property of type `R` and an optional `value` property of type `T`.
+ * @template {CollectionShape<E, T, R>} [C=CollectionShape<E, T, R>]
  */
-type CollectionConstructor<T, V, C extends CollectionShape<T, V>> = ConstrainedConstructor<CollectionShape<T, V>, C, T[]>;
+type CollectionConstructor<E, T, R extends boolean = false, G extends {
+    async?: R;
+    value?: T;
+} = {
+    async?: R;
+    value?: T;
+}, C extends CollectionShape<E, T, R> = CollectionShape<E, T, R>> = ConstrainedConstructor<CollectionShape<E, T, R>, C, [
+    G,
+    ...E[]
+]>;
 
-export type { CollectionAdapter, CollectionConstructor, CollectionShape };
+export type { CollectionAdapter, CollectionAdapterConstructor, CollectionConstructor, CollectionShape };