@typedly/collection 4.0.0 → 5.0.0

package/README.md

@@ -27,12 +27,15 @@ A **TypeScript** type definitions package for data collections with customizable
 
 - [Installation](#installation)
 - [Api](#api)
-  - Interface
-    - [`CollectionAdapter`](#collectionadapter)
+  - Constructor
     - [`CollectionAdapterConstructor`](#collectionadapterconstructor)
-    - [`CollectionShape`](#collectionshape)
-  - Type
     - [`CollectionConstructor`](#collectionconstructor)
+    - [`ConfigurableCollectionAdapterConstructor`](#configurablecollectionadapterconstructor)
+    - [`ConfigurableCollectionConstructor`](#configurablecollectionconstructor)
+  - Main
+    - [`CollectionAdapter`](#collectionadapter)
+    - [`CollectionSettings`](#collectionsettings)
+    - [`CollectionShape`](#collectionshape)
 - [Contributing](#contributing)
 - [Support](#support)
 - [Code of Conduct](#code-of-conduct)
@@ -51,24 +54,20 @@ npm install @typedly/collection --save-peer
 
 ```typescript
 import {
+  // Constructor.
+  CollectionAdapterConstructor,
+  CollectionConstructor,
+  ConfigurableCollectionAdapterConstructor,
   // Interface.
   CollectionAdapter,
-  CollectionAdapterConstructor,
+  CollectionSettings,
   CollectionShape,
-  // Type.
-  CollectionConstructor
 } from '@typedly/collection';
 ```
 
 ### Interface
 
-### `CollectionAdapter`
-
-The adapter interface for collections.
-
-```typescript
-import { CollectionAdapter } from '@typedly/collection';
-```
+### Constructor
 
 ### `CollectionAdapterConstructor`
 
@@ -92,14 +91,13 @@ export class ExampleCollectionAdapter<
     return this.#items.length;
   }
   public get  value(): T {
-    // Implementation depends on specific requirements.
-    return {} as T;
+    return this.#items as T;
   }
   version = "1.0.0";
   #async: R;
   #items: E[] = [];
-  constructor({async}: {async: R}, ...elements: E[]) {
-    this.#async = async;
+  constructor(...elements: E[]) {
+    this.#async = false as R;
     this.#items.push(...elements);
   }
   public add(...element: E[]): AsyncReturn<R, this> {
@@ -129,22 +127,19 @@ export class ExampleCollectionAdapter<
     return this as AsyncReturn<R, this>;
   }
   public getValue(): AsyncReturn<R, T> {
-    // Implementation depends on specific requirements.
-    return {} as 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 setValue(value: T): AsyncReturn<R, this> {
-    // Implementation depends on specific requirements.
+    this.#items = value as unknown as E[];
     return this as AsyncReturn<R, this>;
   }
   public unlock(): AsyncReturn<R, this> {
-    // Implementation depends on specific requirements.
     return this as AsyncReturn<R, this>;
   }
 }
@@ -156,18 +151,52 @@ function createAdapter<
   R extends boolean = false,
   A extends CollectionAdapter<E, T, R> = CollectionAdapter<E, T, R>
 >(
-  AdapterCtor: CollectionAdapterConstructor<E, T, R, { async: R }, A>,
-  async: R,
+  AdapterCtor: CollectionAdapterConstructor<E, T, R, A>,
   ...elements: E[]
 ): A {
-  return new AdapterCtor({ async }, ...elements);
+  return new AdapterCtor(...elements);
 }
 
 // ExampleCollectionAdapter<number, unknown, false>
-const adapter1 = createAdapter(ExampleCollectionAdapter, false, 1, 2, 3);
+const adapter1 = createAdapter(ExampleCollectionAdapter, 1, 2, 3);
 // ExampleCollectionAdapter<string, unknown, true>
-const adapter2 = createAdapter(ExampleCollectionAdapter, true, 'a', 'b', 'c');
+const adapter2 = createAdapter(ExampleCollectionAdapter, 'a', 'b', 'c');
+```
+
+### `CollectionConstructor`
+
+```typescript
+import { CollectionConstructor } from '@typedly/collection';
+```
+
+### `ConfigurableCollectionAdapterConstructor`
+
+```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`
+
+Represents the settings for a collection.
 
+```typescript
+import { CollectionSettings } from '@typedly/collection';
 ```
 
 ### `CollectionShape`
@@ -182,15 +211,12 @@ export class AnyCollection<
   E,
   T = Set<E>
 > implements CollectionShape<E, T, false> {
-  async = false as false;
+  get size(): number { return (this.#items as any).size; }
+  get value(): T { return this.#items; }
+  get [Symbol.toStringTag](): string { return 'AnyCollection'; }
 
-  // Data shape method.
-  get value(): T {
-    // Implementation depends on specific requirements.
-    return this.#items;
-  }
+  async = false as false;
 
-  // Example internal storage.
   #items: T;
 
   constructor(
@@ -203,61 +229,19 @@ export class AnyCollection<
     elements.forEach(element => (this.#items as any).add(element));
   }
 
-  public clear(): this {
-    // Implementation depends on specific requirements.
-    return this;
-  }
-  public destroy(): this {
-    // Implementation depends on specific requirements.
-    return this;
-  }
-  public lock(): this {
-    // Implementation depends on specific requirements.
-    return 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 {
-    // Implementation depends on specific requirements.
-    return this;
-  }
-
-
-  add(element: E): this {
-    (this.#items as any).add(element);
-    return this;
-  }
-
-  delete(element: E): boolean {
-    return (this.#items as any).delete(element);
-  }
-
+  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);
-    });
+    (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);
-  }
-
-  get size(): number {
-    return (this.#items as any).size;
-  }
-
-  get [Symbol.toStringTag](): string {
-    return 'MyCollection';
-  }
-
+  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();
   }
@@ -284,14 +268,6 @@ const anyCollection2 = new AnyCollection<{age: number}, Set<{age: number}>>(
 console.log(`anyCollection2:`, anyCollection2.value);
 ```
 
-### Type
-
-### `CollectionConstructor`
-
-```typescript
-import { CollectionConstructor } from '@typedly/collection';
-```
-
 ## Contributing
 
 Your contributions are valued! If you'd like to contribute, please feel free to submit a pull request. Help is always appreciated.
@@ -308,6 +284,7 @@ Support via:
 - [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": "4.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",

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
@@ -17,6 +111,12 @@ interface CollectionShape<E, T = any, R extends boolean = false> extends DataSha
      * @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}
@@ -46,6 +146,23 @@ interface CollectionShape<E, T = any, R extends boolean = false> extends DataSha
      * @returns {AsyncReturn<R, boolean>} `true` if the element exists, otherwise `false`.
      */
     has(...element: E[]): AsyncReturn<R, boolean>;
+    /**
+     * @description Sets the asynchronous mode of the collection.
+     * @param {R} async The boolean type to determine async methods.
+     * @returns {this} The collection instance `this`.
+     */
+    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>;
 }
 
 /**
@@ -65,19 +182,13 @@ interface CollectionAdapter<E, T, R extends boolean = false> extends CollectionS
  * @description The interface of adapter constructor.
  * @export
  * @interface CollectionAdapterConstructor
- * @template E Elements type.
+ * @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 {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>]
+ * @template {CollectionAdapter<E, T, R>} [A=CollectionAdapter<E, T, R>] The adapter type.
  */
-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;
+interface CollectionAdapterConstructor<E, T, R extends boolean = false, A extends CollectionAdapter<E, T, R> = CollectionAdapter<E, T, R>> {
+    new (...elements: E[]): A;
 }
 
 /**
@@ -85,19 +196,25 @@ interface CollectionAdapterConstructor<E, T, R extends boolean = false, C extend
  * @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 {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>]
+ * @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.
  */
-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,
+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']>]
+ */
+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, CollectionAdapterConstructor, CollectionConstructor, CollectionShape };
+export type { CollectionAdapter, CollectionAdapterConstructor, CollectionConstructor, CollectionSettings, CollectionShape, ConfigurableCollectionAdapterConstructor };