@typedly/collection 2.0.0 → 3.0.0

package/README.md

@@ -71,9 +71,12 @@ import { CollectionAdapter } from '@typedly/collection';
 ### `CollectionShape`
 
 ```typescript
-import { CollectionShape } from '@typedly/collection';
+import { CollectionShape, IterValue } from '@typedly/collection';
 
-export class AnyCollection<T, V = Set<T>> implements CollectionShape<T, V> {
+export class AnyCollection<
+  T,
+  V = Set<T>
+> implements CollectionShape<T, V, false> {
   // Data shape method.
   get value(): V {
     // Implementation depends on specific requirements.
@@ -121,10 +124,11 @@ export class AnyCollection<T, V = Set<T>> implements CollectionShape<T, V> {
     return (this.#items as any).delete(element);
   }
 
-  forEach(callbackfn: (element: T, element2: T, collection: CollectionShape<T, V>) => void, thisArg?: any): void {
+  forEach(callbackfn: (element: T, element2: T, collection: CollectionShape<T, V, false>) => void, thisArg?: any): this {
     (this.#items as any).forEach((value: T) => {
       callbackfn.call(thisArg, value, value, this);
     });
+    return this;
   }
 
   has(element: T): boolean {
@@ -139,7 +143,7 @@ export class AnyCollection<T, V = Set<T>> implements CollectionShape<T, V> {
     return 'MyCollection';
   }
 
-  [Symbol.iterator](): Iterator<T> {
+  [Symbol.iterator](): IterableIterator<IterValue<V>> {
     return (this.#items as any).values();
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typedly/collection",
-  "version": "2.0.0",
+  "version": "3.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": "^3.0.0"
   },
   "repository": {
     "type": "git",

package/types/typedly-collection.d.ts

@@ -1,75 +1,68 @@
-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.
+     * @param {...E[]} element Element of type `T` to add.
+     * @returns {AsyncReturn<R, this>} The collection instance `this`, or in `Promise`.
      */
-    add(...element: T[]): this;
+    add(...element: E[]): AsyncReturn<R, 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`.
+     * @param {...E[]} element Element of type `T` to delete.
+     * @returns {AsyncReturn<R, boolean>} `true` if the element was successfully deleted, otherwise `false`.
      */
-    delete(...element: T[]): boolean;
+    delete(...element: E[]): AsyncReturn<R, boolean>;
     /**
      * @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`.
+     * @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`.
      */
-    forEach(callbackfn: (element: T, element2: T, collection: CollectionShape<T, V>) => void, thisArg?: any): void;
+    forEach(callbackfn: (element: E, element2: E, collection: CollectionShape<E, T, R>) => void, thisArg?: any): AsyncReturn<R, this>;
     /**
      * @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`.
+     * @param {...E[]} element Element of type `T` to check for existence.
+     * @returns {AsyncReturn<R, boolean>} `true` if the element exists, otherwise `false`.
      */
-    has(...element: T[]): boolean;
+    has(...element: E[]): AsyncReturn<R, boolean>;
     /**
      * @description The number of items in the collection.
      * @returns {number}
      */
     readonly size: number;
-    /**
-     * @description Returns a tag name for collection.
-     * @returns {string}
-     */
-    get [Symbol.toStringTag](): string;
-    /**
-     * @description Returns an iterator for the collection.
-     * @returns {Iterator<T>}
-     */
-    [Symbol.iterator](): Iterator<T>;
 }
 
 /**
  * @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 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 {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, C extends CollectionShape<E, T, R> = CollectionShape<E, T, R>> = ConstrainedConstructor<CollectionShape<E, T, R>, C, E[]>;
 
 export type { CollectionAdapter, CollectionConstructor, CollectionShape };