@typedly/collection 3.0.0 → 5.0.0

package/README.md

@@ -27,11 +27,15 @@ A **TypeScript** type definitions package for data collections with customizable
 
 - [Installation](#installation)
 - [Api](#api)
-  - Interface
+  - Constructor
+    - [`CollectionAdapterConstructor`](#collectionadapterconstructor)
+    - [`CollectionConstructor`](#collectionconstructor)
+    - [`ConfigurableCollectionAdapterConstructor`](#configurablecollectionadapterconstructor)
+    - [`ConfigurableCollectionConstructor`](#configurablecollectionconstructor)
+  - Main
     - [`CollectionAdapter`](#collectionadapter)
+    - [`CollectionSettings`](#collectionsettings)
     - [`CollectionShape`](#collectionshape)
-  - Type
-    - [`CollectionConstructor`](#collectionconstructor)
 - [Contributing](#contributing)
 - [Support](#support)
 - [Code of Conduct](#code-of-conduct)
@@ -50,100 +54,195 @@ npm install @typedly/collection --save-peer
 
 ```typescript
 import {
+  // Constructor.
+  CollectionAdapterConstructor,
+  CollectionConstructor,
+  ConfigurableCollectionAdapterConstructor,
   // Interface.
   CollectionAdapter,
+  CollectionSettings,
   CollectionShape,
-  // Type.
-  CollectionConstructor
 } from '@typedly/collection';
 ```
 
 ### Interface
 
-### `CollectionAdapter`
+### Constructor
 
-The adapter interface for collections.
+### `CollectionAdapterConstructor`
 
-```typescript
-import { CollectionAdapter } from '@typedly/collection';
-```
-
-### `CollectionShape`
+The interface of adapter constructor.
 
 ```typescript
-import { CollectionShape, IterValue } from '@typedly/collection';
-
-export class AnyCollection<
+import { CollectionAdapter, CollectionAdapterConstructor } from '@typedly/collection';
+import { AsyncReturn } from '@typedly/data';
+/**
+ * Example class with fake async returned types.
+ */
+export class ExampleCollectionAdapter<
+  E,
   T,
-  V = Set<T>
-> implements CollectionShape<T, V, false> {
-  // Data shape method.
-  get value(): V {
-    // Implementation depends on specific requirements.
-    return {} as V;
+  R extends boolean = false, 
+> implements CollectionAdapter<E, T, R> {
+  public get async(): R {
+    return this.#async;
   }
-
-  // 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));
+  public get size(): number {
+    return this.#items.length;
+  }
+  public get  value(): T {
+    return this.#items as T;
+  }
+  version = "1.0.0";
+  #async: R;
+  #items: E[] = [];
+  constructor(...elements: E[]) {
+    this.#async = false as R;
+    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 clear(): this {
-    // Implementation depends on specific requirements.
-    return this;
+  public destroy(): AsyncReturn<R, this> {
+    this.#items = [];
+    return this as AsyncReturn<R, this>;
   }
-  public destroy(): this {
-    // Implementation depends on specific requirements.
-    return 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> {
+    return this.#items 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 set(value: V): this {
-    // Implementation depends on specific requirements.
-    return this;
+  public setValue(value: T): AsyncReturn<R, this> {
+    this.#items = value as unknown as E[];
+    return this as AsyncReturn<R, this>;
   }
-  public unlock(): this {
-    // Implementation depends on specific requirements.
-    return this;
+  public unlock(): AsyncReturn<R, this> {
+    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, A>,
+  ...elements: E[]
+): A {
+  return new AdapterCtor(...elements);
+}
 
-  add(element: T): this {
-    (this.#items as any).add(element);
-    return this;
-  }
+// ExampleCollectionAdapter<number, unknown, false>
+const adapter1 = createAdapter(ExampleCollectionAdapter, 1, 2, 3);
+// ExampleCollectionAdapter<string, unknown, true>
+const adapter2 = createAdapter(ExampleCollectionAdapter, 'a', 'b', 'c');
+```
 
-  delete(element: T): boolean {
-    return (this.#items as any).delete(element);
-  }
+### `CollectionConstructor`
 
-  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;
-  }
+```typescript
+import { CollectionConstructor } from '@typedly/collection';
+```
 
-  has(element: T): boolean {
-    return (this.#items as any).has(element);
-  }
+### `ConfigurableCollectionAdapterConstructor`
 
-  get size(): number {
-    return (this.#items as any).size;
-  }
+```typescript
+import { ConfigurableCollectionAdapterConstructor } from '@typedly/collection';
+```
+
+### `ConfigurableCollectionConstructor`
+
+```typescript
+import { ConfigurableCollectionConstructor } from '@typedly/collection';
+```
+
+### Main
+
+### `CollectionAdapter`
+
+The adapter interface for collections.
+
+```typescript
+import { CollectionAdapter } from '@typedly/collection';
+```
+
+### `CollectionSettings`
 
-  get [Symbol.toStringTag](): string {
-    return 'MyCollection';
+Represents the settings for a collection.
+
+```typescript
+import { CollectionSettings } from '@typedly/collection';
+```
+
+### `CollectionShape`
+
+Represents a collection of elements.
+
+```typescript
+import { CollectionShape, IterValue } from '@typedly/collection';
+
+// Example class implementing CollectionShape.
+export class AnyCollection<
+  E,
+  T = Set<E>
+> implements CollectionShape<E, T, false> {
+  get size(): number { return (this.#items as any).size; }
+  get value(): T { return this.#items; }
+  get [Symbol.toStringTag](): string { return 'AnyCollection'; }
+
+  async = false as false;
+
+  #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));
   }
 
-  [Symbol.iterator](): IterableIterator<IterValue<V>> {
+  add(element: E): this { (this.#items as any).add(element); return this; }
+  clear(): this { return this; }
+  delete(element: E): boolean { return (this.#items as any).delete(element); }
+  destroy(): this { return this; }
+  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: E): boolean { return (this.#items as any).has(element); }
+  lock(): this { return this; }
+  getValue(): T { return this.#items; }
+  setValue(value: T): this { this.#items = value; return this; }
+  unlock(): this { return this; }
+  [Symbol.iterator](): IterableIterator<IterValue<T>> {
     return (this.#items as any).values();
   }
 }
@@ -151,18 +250,22 @@ export class AnyCollection<
 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);
-```
 
-### Type
+console.log(`anyCollection1:`, anyCollection1.value);
 
-### `CollectionConstructor`
+const anyCollection2 = new AnyCollection<{age: number}, Set<{age: number}>>(
+  { async: false }, Set)
+  .add(obj1)
+  .add(obj2)
+  .add(obj3);
 
-```typescript
-import { CollectionConstructor } from '@typedly/collection';
+console.log(`anyCollection2:`, anyCollection2.value);
 ```
 
 ## Contributing
@@ -176,10 +279,12 @@ 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)
+- [PayPal](https://paypal.me/sterblack)
 
 or via Trust Wallet
 

package/package.json

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

package/types/typedly-collection.d.ts

@@ -1,6 +1,100 @@
 import { DataShape, AsyncReturn } from '@typedly/data';
 import { ConstrainedConstructor } from '@typedly/constructor';
 
+/**
+ * @description Represents the settings for a collection.
+ * @export
+ * @interface CollectionSettings
+ * @template E The type of the elements in the collection.
+ * @template T The type of the value in the collection.
+ * @template {boolean} [R=false] The `boolean` type to determine async methods.
+ */
+interface CollectionSettings<E, T, R extends boolean = false> {
+    /**
+     * @description The asynchronous mode of the collection. If `true`, collection methods will return Promises.
+     * @default false
+     * @type {?R}
+     */
+    async?: R;
+    /**
+     * @description The initial value of the collection. The type of the value is determined by the generic type `T`. If not provided, it defaults to `undefined`.
+     * @type {?T}
+     */
+    value?: T;
+    /**
+     * @description The maximum number of items the collection can hold. If not provided, it defaults to `undefined`, indicating no limit.
+     * @default undefined
+     * @type {?number}
+     */
+    maxSize?: number;
+    /**
+     * @description The initial capacity of the collection. This is a hint for optimization and does not limit the number of items. If not provided, it defaults to `undefined`.
+     * @default undefined
+     * @type {?number}
+     */
+    capacity?: number;
+    /**
+     * @description Indicates whether the collection should automatically sort its elements. If `true`, the collection will maintain its elements in sorted order based on the provided `comparator` function. If not provided, it defaults to `false`.
+     * @default false
+     * @type {?boolean}
+     */
+    autoSort?: boolean;
+    /**
+     * @description A function that defines the sort order of the collection's elements. It should return a negative number if `a` should come before `b`, a positive number if `a` should come after `b`, or `0` if they are considered equal. If not provided, it defaults to `undefined`.
+     * @type {?(a: E, b: E) => number}
+     */
+    comparator?: (a: E, b: E) => number;
+    /**
+     * @description Indicates whether the collection should enforce uniqueness of its elements. If `true`, the collection will not allow duplicate elements. If not provided, it defaults to `false`.
+     * @default false
+     * @type {?boolean}
+     */
+    unique?: boolean;
+    /**
+     * @description Indicates whether the collection should be immutable. If `true`, the collection will not allow modifications after it has been created. If not provided, it defaults to `false`.
+     * @default false
+     * @type {?boolean}
+     */
+    immutable?: boolean;
+    /**
+     * @description Indicates whether the collection should log its actions. If `true`, the collection will log actions such as additions, removals, and updates. If not provided, it defaults to `false`.
+     * @default false
+     * @type {?boolean}
+     */
+    log?: boolean;
+    /**
+     * @description Indicates whether the collection should be lazily initialized. If `true`, the collection will delay initialization until it is first accessed. If not provided, it defaults to `false`.
+     * @default false
+     * @type {?boolean}
+     */
+    lazy?: boolean;
+    /**
+     * @description The maximum time, in milliseconds, that the collection will wait for an operation to complete before timing out. If not provided, it defaults to `undefined`, indicating no timeout.
+     * @type {?number}
+     */
+    timeout?: number;
+    /**
+     * @description The number of items to prefetch in the collection. If not provided, it defaults to `undefined`, indicating no prefetching.
+     * @type {?number}
+     */
+    prefetch?: number;
+    /**
+     * @description Indicates whether the collection should be locked. If `true`, the collection will not allow any modifications after it has been created. If not provided, it defaults to `false`.
+     * @default false
+     * @type {?boolean}
+     */
+    locked?: boolean;
+    /**
+     * @description The name of the collection. If not provided, it defaults to `undefined`.
+     * @type {?string}
+     */
+    name?: string;
+    /**
+     * @description Function to validate elements before adding
+     */
+    validator?: (element: E) => boolean;
+}
+
 /**
  * @description Represents a collection of elements.
  * @export
@@ -11,6 +105,23 @@ import { ConstrainedConstructor } from '@typedly/constructor';
  * @extends {DataShape<T, R>}
  */
 interface CollectionShape<E, T = any, R extends boolean = false> extends DataShape<T, R> {
+    /**
+     * @description Indicates whether the collection operates in asynchronous mode.
+     * @readonly
+     * @type {R}
+     */
+    readonly async: R;
+    /**
+     * @description The configuration settings of the collection.
+     * @readonly
+     * @type {?CollectionSettings<E, T, R>}
+     */
+    readonly configuration?: CollectionSettings<E, T, R>;
+    /**
+     * @description The number of items in the collection.
+     * @returns {number}
+     */
+    readonly size: number;
     /**
      * @description Adds elements to the collection.
      * @param {...E[]} element Element of type `T` to add.
@@ -36,10 +147,22 @@ interface CollectionShape<E, T = any, R extends boolean = false> extends DataSha
      */
     has(...element: E[]): AsyncReturn<R, boolean>;
     /**
-     * @description The number of items in the collection.
-     * @returns {number}
+     * @description Sets the asynchronous mode of the collection.
+     * @param {R} async The boolean type to determine async methods.
+     * @returns {this} The collection instance `this`.
      */
-    readonly size: number;
+    setAsync?(async: R): this;
+    /**
+     * @description Converts the collection to an array of elements.
+     * @returns {AsyncReturn<R, E[]>} The array of elements, or in `Promise` if `R` is `true`.
+     */
+    toArray?(): AsyncReturn<R, E[]>;
+    /**
+     * @description
+     * @param {R} async
+     * @returns {CollectionShape<E, T, R>}
+     */
+    with?(async: R): CollectionShape<E, T, R>;
 }
 
 /**
@@ -55,14 +178,43 @@ interface CollectionAdapter<E, T, R extends boolean = false> extends CollectionS
     version: string;
 }
 
+/**
+ * @description The interface of adapter constructor.
+ * @export
+ * @interface CollectionAdapterConstructor
+ * @template E Elements type of `T`.
+ * @template T Value type under which the elements are stored.
+ * @template {boolean} [R=false] The boolean type indicates the async methods.
+ * @template {CollectionAdapter<E, T, R>} [A=CollectionAdapter<E, T, R>] The adapter type.
+ */
+interface CollectionAdapterConstructor<E, T, R extends boolean = false, A extends CollectionAdapter<E, T, R> = CollectionAdapter<E, T, R>> {
+    new (...elements: E[]): A;
+}
+
 /**
  * @description The constructor type for CollectionShape.
  * @export
  * @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>]
+ * @template {boolean} [R=false] The boolean type indicates the async methods.
+ * @template {CollectionShape<E, T, R>} [S=CollectionShape<E, T, R>] The collection shape type.
+ */
+interface CollectionConstructor<E, T, R extends boolean = false, S extends CollectionShape<E, T, R> = CollectionShape<E, T, R>> extends ConstrainedConstructor<CollectionShape<E, T, R>, S, [
+    ...E[]
+]> {
+}
+
+/**
+ * @description The interface of adapter constructor with configurable async mode.
+ * @export
+ * @interface ConfigurableCollectionAdapterConstructor
+ * @template E Elements type of `T`.
+ * @template T Value type under which the elements are stored.
+ * @template {CollectionSettings<E, T, any>} [C=CollectionSettings<E, T, any>]
+ * @template {CollectionAdapter<E, T, C['async']>} [A=CollectionAdapter<E, T, C['async']>]
  */
-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[]>;
+interface ConfigurableCollectionAdapterConstructor<E, T, C extends CollectionSettings<E, T, any> = CollectionSettings<E, T, any>, A extends CollectionAdapter<E, T, C['async']> = CollectionAdapter<E, T, C['async']>> {
+    new (settings: C, ...elements: E[]): A;
+}
 
-export type { CollectionAdapter, CollectionConstructor, CollectionShape };
+export type { CollectionAdapter, CollectionAdapterConstructor, CollectionConstructor, CollectionSettings, CollectionShape, ConfigurableCollectionAdapterConstructor };