@typedly/collection 5.0.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +106 -190
  2. package/package.json +23 -3
  3. package/types/typedly-collection.d.ts +100 -121
package/README.md CHANGED
@@ -1,16 +1,26 @@
1
1
  <a href="https://github.com/typescript-package">
2
2
  <img
3
3
  src="https://avatars.githubusercontent.com/u/189665258?s=150&u=712e292bae048947d1f7d2020d7d38875c40e63a&v=4"
4
- title="@typedly/collection - A TypeScript type definitions package for data collection."
4
+ title="@typedly/collection - A TypeScript type definitions package for data collections with customizable storage."
5
5
  />
6
6
  </a>
7
7
 
8
8
  ## @typedly/collection
9
9
 
10
10
  <!-- npm badge -->
11
- [![npm version][typedly-npm-badge-svg]][typedly-npm-badge]
12
- [![GitHub issues][typedly-badge-issues]][typedly-issues]
13
- [![GitHub license][typedly-badge-license]][typedly-license]
11
+ [![npm version][package-npm-badge-svg]][package-npm-badge]
12
+ [![GitHub issues][package-badge-issues]][package-issues]
13
+ [![GitHub license][package-badge-license]][package-license]
14
+
15
+ <!-- GitHub badges -->
16
+ [![GitHub issues][package-badge-issues]][package-issues]
17
+ [![GitHub forks][package-badge-forks]][package-forks]
18
+ [![GitHub stars][package-badge-stars]][package-stars]
19
+ [![GitHub license][package-badge-license]][package-license]
20
+
21
+ <!-- Sponsors -->
22
+ [![GitHub Sponsors][github-badge-sponsor]][github-sponsor-link]
23
+ [![Patreon Sponsors][patreon-badge]][patreon-link]
14
24
 
15
25
  A **TypeScript** type definitions package for data collections with customizable storage.
16
26
 
@@ -25,15 +35,18 @@ A **TypeScript** type definitions package for data collections with customizable
25
35
 
26
36
  ## Table of contents
27
37
 
38
+ - [Related packages](#related-packages)
28
39
  - [Installation](#installation)
29
40
  - [Api](#api)
30
- - Constructor
41
+ - [Adapter](#adapter)
31
42
  - [`CollectionAdapterConstructor`](#collectionadapterconstructor)
32
- - [`CollectionConstructor`](#collectionconstructor)
33
- - [`ConfigurableCollectionAdapterConstructor`](#configurablecollectionadapterconstructor)
34
- - [`ConfigurableCollectionConstructor`](#configurablecollectionconstructor)
35
- - Main
36
43
  - [`CollectionAdapter`](#collectionadapter)
44
+ - [Inference](#inference)
45
+ - [`InferCollectionType`](#infercollectiontype)
46
+ - [`InferElementFromSettings`](#inferelementfromsettings)
47
+ - [`InferElement`](#inferelement)
48
+ - [Main](#main)
49
+ - [`CollectionConstructor`](#collectionconstructor)
37
50
  - [`CollectionSettings`](#collectionsettings)
38
51
  - [`CollectionShape`](#collectionshape)
39
52
  - [Contributing](#contributing)
@@ -43,6 +56,25 @@ A **TypeScript** type definitions package for data collections with customizable
43
56
  - [Commit](#commit)
44
57
  - [Versioning](#versioning)
45
58
  - [License](#license)
59
+ - [Packages](#packages)
60
+
61
+ ## Related packages
62
+
63
+ ### Peer dependencies
64
+
65
+ - **[@typedly/adaptable-data](https://github.com/typedly/adaptable-data)**: A **TypeScript** type definitions package for configurable, composable, trait-driven adaptable data models with adapter support.
66
+ - **[@typedly/configurable-data](https://github.com/typedly/configurable-data)**: A **TypeScript** type definitions package for configurable, composable, trait-driven data models.
67
+ - **[@typedly/data-traits](https://github.com/typedly/data-traits)**: A **TypeScript** type definitions package for configurable data traits, providing various kinds of configurable data interfaces.
68
+ - **[@typedly/data](https://github.com/typedly/data)**: A **TypeScript** type definitions for [`@typescript-package/data`](https://github.com/typedly/data).
69
+
70
+ ### General
71
+
72
+ - **[@typedly/adaptable-data](https://github.com/typedly/adaptable-data)**: A **TypeScript** type definitions for data adapter.
73
+ - **[@typedly/adaptable-collection](https://github.com/typedly/adaptable-collection)**: A **TypeScript** type definitions package for adaptable collections with configuration and adapter support.
74
+ - **[@typedly/configurable-collection](https://github.com/typedly/configurable-collection)**: A **TypeScript** type definitions package for configurable collections with configuration.
75
+ - **[@typedly/collection](https://github.com/typedly/collection)**: A **TypeScript** type definitions package for data collections with customizable storage.
76
+ - **[@typescript-package/data](https://github.com/typescript-package/data)**: A lightweight **TypeScript** library for basic data management.
77
+ - **[@typescript-package/collection](https://github.com/typescript-package/collection)**: A lightweight **TypeScript** library for data collection.
46
78
 
47
79
  ## Installation
48
80
 
@@ -54,12 +86,19 @@ npm install @typedly/collection --save-peer
54
86
 
55
87
  ```typescript
56
88
  import {
89
+ // Adapter.
90
+ CollectionAdapter,
91
+
57
92
  // Constructor.
58
93
  CollectionAdapterConstructor,
59
94
  CollectionConstructor,
60
- ConfigurableCollectionAdapterConstructor,
95
+
96
+ // Inference.
97
+ InferCollectionType,
98
+ InferElementFromSettings,
99
+ InferElement,
100
+
61
101
  // Interface.
62
- CollectionAdapter,
63
102
  CollectionSettings,
64
103
  CollectionShape,
65
104
  } from '@typedly/collection';
@@ -67,128 +106,58 @@ import {
67
106
 
68
107
  ### Interface
69
108
 
70
- ### Constructor
109
+ ### Adapter
110
+
111
+ ### `CollectionAdapter`
112
+
113
+ The adapter interface for collections.
114
+
115
+ ```typescript
116
+ import { CollectionAdapter } from '@typedly/collection';
117
+ ```
71
118
 
72
119
  ### `CollectionAdapterConstructor`
73
120
 
74
121
  The interface of adapter constructor.
75
122
 
76
123
  ```typescript
77
- import { CollectionAdapter, CollectionAdapterConstructor } from '@typedly/collection';
78
- import { AsyncReturn } from '@typedly/data';
79
- /**
80
- * Example class with fake async returned types.
81
- */
82
- export class ExampleCollectionAdapter<
83
- E,
84
- T,
85
- R extends boolean = false,
86
- > implements CollectionAdapter<E, T, R> {
87
- public get async(): R {
88
- return this.#async;
89
- }
90
- public get size(): number {
91
- return this.#items.length;
92
- }
93
- public get value(): T {
94
- return this.#items as T;
95
- }
96
- version = "1.0.0";
97
- #async: R;
98
- #items: E[] = [];
99
- constructor(...elements: E[]) {
100
- this.#async = false as R;
101
- this.#items.push(...elements);
102
- }
103
- public add(...element: E[]): AsyncReturn<R, this> {
104
- this.#items.push(...element);
105
- return this as AsyncReturn<R, this>;
106
- }
107
- public clear(): AsyncReturn<R, this> {
108
- this.#items = [];
109
- return this as AsyncReturn<R, this>;
110
- }
111
- public delete(...element: E[]): AsyncReturn<R, boolean> {
112
- const index = this.#items.indexOf(element[0]);
113
- if (index !== -1) {
114
- this.#items.splice(index, 1);
115
- return true as AsyncReturn<R, boolean>;
116
- }
117
- return false as AsyncReturn<R, boolean>;
118
- }
119
- public destroy(): AsyncReturn<R, this> {
120
- this.#items = [];
121
- return this as AsyncReturn<R, this>;
122
- }
123
- public forEach(callbackfn: (element: E, element2: E, collection: CollectionAdapter<E, T, R>) => void, thisArg?: any): AsyncReturn<R, this> {
124
- this.#items.forEach((value: E) => {
125
- callbackfn.call(thisArg, value, value, this);
126
- });
127
- return this as AsyncReturn<R, this>;
128
- }
129
- public getValue(): AsyncReturn<R, T> {
130
- return this.#items as AsyncReturn<R, T>;
131
- }
132
- public has(element: E): AsyncReturn<R, boolean> {
133
- return this.#items.includes(element) as AsyncReturn<R, boolean>;
134
- }
135
- public lock(): this {
136
- return this;
137
- }
138
- public setValue(value: T): AsyncReturn<R, this> {
139
- this.#items = value as unknown as E[];
140
- return this as AsyncReturn<R, this>;
141
- }
142
- public unlock(): AsyncReturn<R, this> {
143
- return this as AsyncReturn<R, this>;
144
- }
145
- }
146
-
147
- // Create factory function for creating adapter instances.
148
- function createAdapter<
149
- E,
150
- T,
151
- R extends boolean = false,
152
- A extends CollectionAdapter<E, T, R> = CollectionAdapter<E, T, R>
153
- >(
154
- AdapterCtor: CollectionAdapterConstructor<E, T, R, A>,
155
- ...elements: E[]
156
- ): A {
157
- return new AdapterCtor(...elements);
158
- }
159
-
160
- // ExampleCollectionAdapter<number, unknown, false>
161
- const adapter1 = createAdapter(ExampleCollectionAdapter, 1, 2, 3);
162
- // ExampleCollectionAdapter<string, unknown, true>
163
- const adapter2 = createAdapter(ExampleCollectionAdapter, 'a', 'b', 'c');
124
+ import { CollectionAdapterConstructor } from '@typedly/collection';
164
125
  ```
165
126
 
166
- ### `CollectionConstructor`
127
+ ### Inference
128
+
129
+ ### `InferCollectionType`
130
+
131
+ Infer the collection type from the collection settings or adapter.
167
132
 
168
133
  ```typescript
169
- import { CollectionConstructor } from '@typedly/collection';
134
+ import { InferCollectionType } from '@typedly/collection';
170
135
  ```
171
136
 
172
- ### `ConfigurableCollectionAdapterConstructor`
137
+ ### `InferElementFromSettings`
138
+
139
+ Type to infer the element type from collection settings or adapter.
173
140
 
174
141
  ```typescript
175
- import { ConfigurableCollectionAdapterConstructor } from '@typedly/collection';
142
+ import { InferElementFromSettings } from '@typedly/collection';
176
143
  ```
177
144
 
178
- ### `ConfigurableCollectionConstructor`
145
+ ### `InferElement`
146
+
147
+ Type to infer the element type from collection settings or adapter, with special handling for common collection types like Set, Array, and Map.
179
148
 
180
149
  ```typescript
181
- import { ConfigurableCollectionConstructor } from '@typedly/collection';
150
+ import { InferElement } from '@typedly/collection';
182
151
  ```
183
152
 
184
153
  ### Main
185
154
 
186
- ### `CollectionAdapter`
155
+ ### `CollectionConstructor`
187
156
 
188
- The adapter interface for collections.
157
+ The constructor type for `CollectionShape`.
189
158
 
190
159
  ```typescript
191
- import { CollectionAdapter } from '@typedly/collection';
160
+ import { CollectionConstructor } from '@typedly/collection';
192
161
  ```
193
162
 
194
163
  ### `CollectionSettings`
@@ -201,71 +170,10 @@ import { CollectionSettings } from '@typedly/collection';
201
170
 
202
171
  ### `CollectionShape`
203
172
 
204
- Represents a collection of elements.
173
+ The `CollectionShape` interface defines the structure and behavior of a collection data structure, which can be implemented by various types of collections such as sets, arrays, or maps.
205
174
 
206
175
  ```typescript
207
- import { CollectionShape, IterValue } from '@typedly/collection';
208
-
209
- // Example class implementing CollectionShape.
210
- export class AnyCollection<
211
- E,
212
- T = Set<E>
213
- > implements CollectionShape<E, T, false> {
214
- get size(): number { return (this.#items as any).size; }
215
- get value(): T { return this.#items; }
216
- get [Symbol.toStringTag](): string { return 'AnyCollection'; }
217
-
218
- async = false as false;
219
-
220
- #items: T;
221
-
222
- constructor(
223
- { async, value }: { async: false, value?: T },
224
- type?: new (...args: any[]) => T,
225
- ...elements: E[]
226
- ) {
227
- this.async = async;
228
- this.#items = type ? new type() : value ? value : {} as T;
229
- elements.forEach(element => (this.#items as any).add(element));
230
- }
231
-
232
- add(element: E): this { (this.#items as any).add(element); return this; }
233
- clear(): this { return this; }
234
- delete(element: E): boolean { return (this.#items as any).delete(element); }
235
- destroy(): this { return this; }
236
- forEach(callbackfn: (element: E, element2: E, collection: CollectionShape<E, T, false>) => void, thisArg?: any): this {
237
- (this.#items as any).forEach((value: E) => callbackfn.call(thisArg, value, value, this));
238
- return this;
239
- }
240
- has(element: E): boolean { return (this.#items as any).has(element); }
241
- lock(): this { return this; }
242
- getValue(): T { return this.#items; }
243
- setValue(value: T): this { this.#items = value; return this; }
244
- unlock(): this { return this; }
245
- [Symbol.iterator](): IterableIterator<IterValue<T>> {
246
- return (this.#items as any).values();
247
- }
248
- }
249
-
250
- const obj1 = {age: 27};
251
- const obj2 = {age: 37};
252
- const obj3 = {age: 47};
253
- const anyCollection1 = new AnyCollection<{age: number}, Set<{age: number}>>(
254
- { async: false, value: new Set([{age: 27}, {age: 37}, {age: 47}]) }
255
- )
256
- .add(obj1)
257
- .add(obj2)
258
- .add(obj3);
259
-
260
- console.log(`anyCollection1:`, anyCollection1.value);
261
-
262
- const anyCollection2 = new AnyCollection<{age: number}, Set<{age: number}>>(
263
- { async: false }, Set)
264
- .add(obj1)
265
- .add(obj2)
266
- .add(obj3);
267
-
268
- console.log(`anyCollection2:`, anyCollection2.value);
176
+ import { CollectionShape } from '@typedly/collection';
269
177
  ```
270
178
 
271
179
  ## Contributing
@@ -278,21 +186,23 @@ If you find this package useful and would like to support its and general develo
278
186
 
279
187
  Support via:
280
188
 
281
- - [Stripe](https://donate.stripe.com/dR614hfDZcJE3wAcMM)
282
- - ~~[Revolut](https://checkout.revolut.com/pay/048b10a3-0e10-42c8-a917-e3e9cb4c8e29)~~
283
- - [GitHub](https://github.com/sponsors/angular-package/sponsorships?sponsor=sciborrudnicki&tier_id=83618)
189
+ - [4Fund](https://4fund.com/bruubs)
284
190
  - [DonorBox](https://donorbox.org/become-a-sponsor-to-the-angular-package?default_interval=o)
191
+ - [GitHub](https://github.com/sponsors/angular-package/sponsorships?sponsor=sciborrudnicki&tier_id=83618)
192
+ - [Ko-fi](https://ko-fi.com/sterblack)
193
+ - [OpenCollective](https://opencollective.com/sterblack)
285
194
  - [Patreon](https://www.patreon.com/checkout/angularpackage?rid=0&fan_landing=true&view_as=public)
286
- - [4Fund](https://4fund.com/bruubs)
287
195
  - [PayPal](https://paypal.me/sterblack)
196
+ - [Stripe](https://donate.stripe.com/dR614hfDZcJE3wAcMM)
197
+ - ~~[Revolut](https://checkout.revolut.com/pay/048b10a3-0e10-42c8-a917-e3e9cb4c8e29)~~
288
198
 
289
199
  or via Trust Wallet
290
200
 
291
- - [XLM](https://link.trustwallet.com/send?coin=148&address=GAFFFB7H3LG42O6JA63FJDRK4PP4JCNEOPHLGLLFH625X2KFYQ4UYVM4)
292
- - [USDT (BEP20)](https://link.trustwallet.com/send?coin=20000714&address=0xA0c22A2bc7E37C1d5992dFDFFeD5E6f9298E1b94&token_id=0x55d398326f99059fF775485246999027B3197955)
293
- - [ETH](https://link.trustwallet.com/send?coin=60&address=0xA0c22A2bc7E37C1d5992dFDFFeD5E6f9298E1b94)
294
- - [BTC](https://link.trustwallet.com/send?coin=0&address=bc1qnf709336tfl57ta5mfkf4t9fndhx7agxvv9svn)
295
201
  - [BNB](https://link.trustwallet.com/send?coin=20000714&address=0xA0c22A2bc7E37C1d5992dFDFFeD5E6f9298E1b94)
202
+ - [BTC](https://link.trustwallet.com/send?coin=0&address=bc1qnf709336tfl57ta5mfkf4t9fndhx7agxvv9svn)
203
+ - [ETH](https://link.trustwallet.com/send?coin=60&address=0xA0c22A2bc7E37C1d5992dFDFFeD5E6f9298E1b94)
204
+ - [USDT (BEP20)](https://link.trustwallet.com/send?coin=20000714&address=0xA0c22A2bc7E37C1d5992dFDFFeD5E6f9298E1b94&token_id=0x55d398326f99059fF775485246999027B3197955)
205
+ - [XLM](https://link.trustwallet.com/send?coin=148&address=GAFFFB7H3LG42O6JA63FJDRK4PP4JCNEOPHLGLLFH625X2KFYQ4UYVM4)
296
206
 
297
207
  ## Code of Conduct
298
208
 
@@ -329,7 +239,7 @@ How do I know when to release 1.0.0?
329
239
 
330
240
  ## License
331
241
 
332
- MIT © typedly ([license][typedly-license])
242
+ MIT © typedly ([license][package-license])
333
243
 
334
244
  ## Packages
335
245
 
@@ -346,23 +256,29 @@ MIT © typedly ([license][typedly-license])
346
256
  - **[@typedly/regexp](https://github.com/typedly/regexp)**: A **TypeScript** type definitions package for `RegExp`.
347
257
  - **[@typedly/symbol](https://github.com/typedly/symbol)**: A **TypeScript** type definitions package for various symbols.
348
258
 
259
+ <!-- Funding -->
260
+ [github-badge-sponsor]: https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&link=https://github.com/sponsors/angular-package
261
+ [github-sponsor-link]: https://github.com/sponsors/angular-package
262
+ [patreon-badge]: https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fshieldsio-patreon.vercel.app%2Fapi%3Fusername%3Dangularpackage%26type%3Dpatrons&style=flat
263
+ [patreon-link]: https://www.patreon.com/join/angularpackage/checkout?fan_landing=true&rid=0
264
+
349
265
  <!-- This package: typedly -->
350
266
  <!-- GitHub: badges -->
351
- [typedly-badge-issues]: https://img.shields.io/github/issues/typedly/collection
352
- [typedly-badge-forks]: https://img.shields.io/github/forks/typedly/collection
353
- [typedly-badge-stars]: https://img.shields.io/github/stars/typedly/collection
354
- [typedly-badge-license]: https://img.shields.io/github/license/typedly/collection
267
+ [package-badge-issues]: https://img.shields.io/github/issues/typedly/collection
268
+ [package-badge-forks]: https://img.shields.io/github/forks/typedly/collection
269
+ [package-badge-stars]: https://img.shields.io/github/stars/typedly/collection
270
+ [package-badge-license]: https://img.shields.io/github/license/typedly/collection
355
271
  <!-- GitHub: badges links -->
356
- [typedly-issues]: https://github.com/typedly/collection/issues
357
- [typedly-forks]: https://github.com/typedly/collection/network
358
- [typedly-license]: https://github.com/typedly/collection/blob/master/LICENSE
359
- [typedly-stars]: https://github.com/typedly/collection/stargazers
272
+ [package-issues]: https://github.com/typedly/collection/issues
273
+ [package-forks]: https://github.com/typedly/collection/network
274
+ [package-license]: https://github.com/typedly/collection/blob/master/LICENSE
275
+ [package-stars]: https://github.com/typedly/collection/stargazers
360
276
  <!-- This package -->
361
277
 
362
278
  <!-- Package: typedly -->
363
279
  <!-- npm -->
364
- [typedly-npm-badge-svg]: https://badge.fury.io/js/@typedly%2Fcollection.svg
365
- [typedly-npm-badge]: https://badge.fury.io/js/@typedly%2Fcollection
280
+ [package-npm-badge-svg]: https://badge.fury.io/js/@typedly%2Fcollection.svg
281
+ [package-npm-badge]: https://badge.fury.io/js/@typedly%2Fcollection
366
282
 
367
283
  <!-- GIT -->
368
284
  [git-semver]: http://semver.org/
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@typedly/collection",
3
- "version": "5.0.0",
3
+ "version": "6.0.0",
4
4
  "author": "wwwdev.io <dev@wwwdev.io>",
5
5
  "description": "A TypeScript type definitions package for data collections with customizable storage.",
6
6
  "license": "MIT",
@@ -9,7 +9,7 @@
9
9
  "registry": "https://registry.npmjs.org"
10
10
  },
11
11
  "peerDependencies": {
12
- "@typedly/data": "^4.0.0"
12
+ "@typedly/adaptable-data": "^4.1.0"
13
13
  },
14
14
  "repository": {
15
15
  "type": "git",
@@ -29,7 +29,27 @@
29
29
  "url": "https://donate.stripe.com/dR614hfDZcJE3wAcMM"
30
30
  },
31
31
  {
32
- "type": "revolut",
32
+ "type": "Donorbox",
33
+ "url": "https://donorbox.org/become-a-sponsor-to-the-angular-package?default_interval=o"
34
+ },
35
+ {
36
+ "type": "Open Collective",
37
+ "url": "https://opencollective.com/sterblack"
38
+ },
39
+ {
40
+ "type": "Ko-fi",
41
+ "url": "https://ko-fi.com/sterblack"
42
+ },
43
+ {
44
+ "type": "4Fund",
45
+ "url": "https://4fund.com/bruubs"
46
+ },
47
+ {
48
+ "type": "paypal",
49
+ "url": "https://paypal.me/sterblack"
50
+ },
51
+ {
52
+ "type": "individual",
33
53
  "url": "https://checkout.revolut.com/pay/048b10a3-0e10-42c8-a917-e3e9cb4c8e29"
34
54
  }
35
55
  ],
package/types/typedly-collection.d.ts CHANGED
@@ -1,21 +1,97 @@
1
- import { DataShape, AsyncReturn } from '@typedly/data';
1
+ import { IterableElement, DataShape, AsyncReturn, DataSettings, InferValue } from '@typedly/data';
2
+ import { Collection } from '@typedly/data-traits';
2
3
  import { ConstrainedConstructor } from '@typedly/constructor';
3
4
 
5
+ /**
6
+ * @description The `CollectionShape` interface defines the structure and behavior of a collection data structure, which can be implemented by various types of collections such as sets, arrays, or maps.
7
+ * It extends the `DataShape` interface, allowing it to inherit common data-related properties and methods while also introducing collection-specific functionalities.
8
+ * @export
9
+ * @interface CollectionShape
10
+ * @template {Iterable<E>} T The iterable collection type.
11
+ * @template [E=IterableElement<T>] The type of elements in the collection inferred from the `T` if possible.
12
+ * @template {boolean} [R=false] The async behavior flag.
13
+ * @extends {DataShape<T, R>} The data-related functionalities defined in `DataShape`.
14
+ * @extends {CollectionTrait<E, R>} The base collection functionalities defined in `CollectionTrait`.
15
+ */
16
+ interface CollectionShape<T extends Iterable<E>, E = IterableElement<T>, R extends boolean = false> extends DataShape<T, R>, Collection<E, R> {
17
+ /**
18
+ * @description Executes a provided function once for each collection element.
19
+ * @param {(element: E, collection: this) => void} callbackfn Function to execute for each element.
20
+ * @param {?*} [thisArg] Value to use as `this` when executing `callbackfn`.
21
+ * @returns {AsyncReturn<R, this>}
22
+ */
23
+ forEach(callbackfn: (element: E, collection: this) => void, thisArg?: any): AsyncReturn<R, this>;
24
+ /**
25
+ * @description Returns an iterable of the values in the collection.
26
+ * The type of the values is determined by the generic type `T`, which represents the iterable collection type.
27
+ * If `T` is not provided, it defaults to `Iterable<unknown>`, and the values will be of type `unknown`.
28
+ * @returns {IterableIterator<IterableElement<T>>}
29
+ */
30
+ [Symbol.iterator](): IterableIterator<IterableElement<T>>;
31
+ }
32
+
33
+ /**
34
+ * @description The adapter interface for collections.
35
+ * @export
36
+ * @interface CollectionAdapter
37
+ * @template {Iterable<E>} T The type of the collection.
38
+ * @template [E=IterableElement<T>] The type of elements in the collection.
39
+ * @template {boolean} [R=false] The async behavior flag.
40
+ * @extends {CollectionShape<T, E, R>} The collection shape interface.
41
+ * @since
42
+ * @version
43
+ * @author Ścibor Rudnicki <sciborrudnicki@wvvw.dev>
44
+ * @see {@link CollectionShape}
45
+ * @see {@link IterableElement}
46
+ * @example
47
+ * ```ts
48
+ * import { CollectionAdapter } from "@typedly/collection";
49
+ *
50
+ * class MyCollectionAdapter implements CollectionAdapter<string[], string, false> {
51
+ * readonly version = "1.0.0";
52
+ * // Implement the methods defined in CollectionShape...
53
+ * }
54
+ */
55
+ interface CollectionAdapter<T extends Iterable<E>, E = IterableElement<T>, R extends boolean = false> extends CollectionShape<T, E, R> {
56
+ readonly version: string;
57
+ }
58
+
59
+ /**
60
+ * @description The interface of adapter constructor.
61
+ * @export
62
+ * @interface CollectionAdapterConstructor
63
+ * @template E Elements type of `T`.
64
+ * @template T Value type under which the elements are stored.
65
+ * @template {boolean} [R=false] The boolean type indicates the async methods.
66
+ * @template {CollectionAdapter<E, T, R>} [A=CollectionAdapter<E, T, R>] The adapter type.
67
+ */
68
+ interface CollectionAdapterConstructor<A extends CollectionAdapter<T, E, R>, E, T extends Iterable<E>, R extends boolean> {
69
+ new (...elements: E[]): A;
70
+ }
71
+
72
+ /**
73
+ * @description The constructor type for `CollectionShape`.
74
+ * @export
75
+ * @interface CollectionConstructor
76
+ * @template {CollectionShape<T, E, R>} S The collection shape type.
77
+ * @template {Iterable<E>} [T=S extends CollectionShape<infer U, any, any> ? U : unknown] The type of the elements in the collection, inferred from the collection shape or defaults to `unknown` if not specified.
78
+ * @template [E=S extends CollectionShape<any, infer U, any> ? U : unknown] The element type inferred from the collection shape or defaults to `unknown` if not specified.
79
+ * @template {boolean} [R=S extends CollectionShape<any, any, infer U> ? U : false] The async behavior flag inferred from the collection shape or defaults to `false` if not specified.
80
+ * @extends {ConstrainedConstructor<CollectionShape<T, E, R>, S, E[]>}
81
+ */
82
+ interface CollectionConstructor<S extends CollectionShape<T, E, R>, T extends Iterable<E> = S extends CollectionShape<infer U, any, any> ? U : unknown, E = S extends CollectionShape<any, infer U, any> ? U : unknown, R extends boolean = S extends CollectionShape<any, any, infer U> ? U : false> extends ConstrainedConstructor<CollectionShape<T, E, R>, S, E[]> {
83
+ }
84
+
4
85
  /**
5
86
  * @description Represents the settings for a collection.
6
87
  * @export
7
88
  * @interface CollectionSettings
8
- * @template E The type of the elements in the collection.
9
- * @template T The type of the value in the collection.
89
+ * @template {Iterable<E>} T The iterable type of the value in the collection.
90
+ * @template [E=IterableElement<T>] The type of the elements in the collection inferred from the `T` if possible.
10
91
  * @template {boolean} [R=false] The `boolean` type to determine async methods.
92
+ * @extends {DataSettings<R>} The base settings for data.
11
93
  */
12
- interface CollectionSettings<E, T, R extends boolean = false> {
13
- /**
14
- * @description The asynchronous mode of the collection. If `true`, collection methods will return Promises.
15
- * @default false
16
- * @type {?R}
17
- */
18
- async?: R;
94
+ interface CollectionSettings<T extends Iterable<E>, E = IterableElement<T>, R extends boolean = false> extends DataSettings<R> {
19
95
  /**
20
96
  * @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`.
21
97
  * @type {?T}
@@ -96,125 +172,28 @@ interface CollectionSettings<E, T, R extends boolean = false> {
96
172
  }
97
173
 
98
174
  /**
99
- * @description Represents a collection of elements.
100
- * @export
101
- * @interface Collection
102
- * @template E The type of elements in the collection.
103
- * @template [T=any] The type of the value in the collection, data of elements.
104
- * @template {boolean} [R=false] The `boolean` type to determine async methods.
105
- * @extends {DataShape<T, R>}
106
- */
107
- interface CollectionShape<E, T = any, R extends boolean = false> extends DataShape<T, R> {
108
- /**
109
- * @description Indicates whether the collection operates in asynchronous mode.
110
- * @readonly
111
- * @type {R}
112
- */
113
- readonly async: R;
114
- /**
115
- * @description The configuration settings of the collection.
116
- * @readonly
117
- * @type {?CollectionSettings<E, T, R>}
118
- */
119
- readonly configuration?: CollectionSettings<E, T, R>;
120
- /**
121
- * @description The number of items in the collection.
122
- * @returns {number}
123
- */
124
- readonly size: number;
125
- /**
126
- * @description Adds elements to the collection.
127
- * @param {...E[]} element Element of type `T` to add.
128
- * @returns {AsyncReturn<R, this>} The collection instance `this`, or in `Promise`.
129
- */
130
- add(...element: E[]): AsyncReturn<R, this>;
131
- /**
132
- * @description Deletes elements from the collection.
133
- * @param {...E[]} element Element of type `T` to delete.
134
- * @returns {AsyncReturn<R, boolean>} `true` if the element was successfully deleted, otherwise `false`.
135
- */
136
- delete(...element: E[]): AsyncReturn<R, boolean>;
137
- /**
138
- * @description Executes a provided function once for each collection element.
139
- * @param {(value: E, value2: E, collection: CollectionShape<E, T, R>) => void} callbackfn Function to execute for each element.
140
- * @param {AsyncReturn<R, this>} [thisArg] Value to use as `this` when executing `callbackfn`.
141
- */
142
- forEach(callbackfn: (element: E, element2: E, collection: CollectionShape<E, T, R>) => void, thisArg?: any): AsyncReturn<R, this>;
143
- /**
144
- * @description Checks if every item exists in the collection.
145
- * @param {...E[]} element Element of type `T` to check for existence.
146
- * @returns {AsyncReturn<R, boolean>} `true` if the element exists, otherwise `false`.
147
- */
148
- has(...element: E[]): AsyncReturn<R, boolean>;
149
- /**
150
- * @description Sets the asynchronous mode of the collection.
151
- * @param {R} async The boolean type to determine async methods.
152
- * @returns {this} The collection instance `this`.
153
- */
154
- setAsync?(async: R): this;
155
- /**
156
- * @description Converts the collection to an array of elements.
157
- * @returns {AsyncReturn<R, E[]>} The array of elements, or in `Promise` if `R` is `true`.
158
- */
159
- toArray?(): AsyncReturn<R, E[]>;
160
- /**
161
- * @description
162
- * @param {R} async
163
- * @returns {CollectionShape<E, T, R>}
164
- */
165
- with?(async: R): CollectionShape<E, T, R>;
166
- }
167
-
168
- /**
169
- * @description The adapter interface for collections.
175
+ * @description Infer the collection type from the collection settings or adapter.
170
176
  * @export
171
- * @interface CollectionAdapter
172
- * @template E The type of elements in the collection.
173
- * @template T The type of the value in the collection, data of elements.
174
- * @template R The `boolean` type to determine async methods.
175
- * @extends {CollectionShape<E, T>}
177
+ * @template C The collection settings type to infer the collection type from.
178
+ * @template [I=undefined] The collection shape type to infer the collection type from if it cannot be inferred from the collection settings.
179
+ * @template [F=unknown] The fallback type to use if the collection type cannot be inferred from the collection settings or the adapter, defaults to `unknown`.
176
180
  */
177
- interface CollectionAdapter<E, T, R extends boolean = false> extends CollectionShape<E, T, R> {
178
- version: string;
179
- }
181
+ type InferCollectionType<C, I = undefined, F = unknown> = C extends CollectionSettings<infer T, any, any> ? T : InferValue<I, F>;
180
182
 
181
183
  /**
182
- * @description The interface of adapter constructor.
184
+ * @description Type to infer the element type from collection settings or adapter.
183
185
  * @export
184
- * @interface CollectionAdapterConstructor
185
- * @template E Elements type of `T`.
186
- * @template T Value type under which the elements are stored.
187
- * @template {boolean} [R=false] The boolean type indicates the async methods.
188
- * @template {CollectionAdapter<E, T, R>} [A=CollectionAdapter<E, T, R>] The adapter type.
186
+ * @template C The collections settings type to infer the element type from.
187
+ * @template [F=unknown] The fallback type if neither settings nor adapter provide an element type.
189
188
  */
190
- interface CollectionAdapterConstructor<E, T, R extends boolean = false, A extends CollectionAdapter<E, T, R> = CollectionAdapter<E, T, R>> {
191
- new (...elements: E[]): A;
192
- }
193
-
194
- /**
195
- * @description The constructor type for CollectionShape.
196
- * @export
197
- * @template E The type of the elements in the collection.
198
- * @template T The type of the value in the collection, data of elements.
199
- * @template {boolean} [R=false] The boolean type indicates the async methods.
200
- * @template {CollectionShape<E, T, R>} [S=CollectionShape<E, T, R>] The collection shape type.
201
- */
202
- 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, [
203
- ...E[]
204
- ]> {
205
- }
189
+ type InferElementFromSettings<C, F = unknown> = C extends CollectionSettings<infer T, infer E, any> ? T extends Iterable<infer U> ? U : E : C extends CollectionSettings<any, infer E, any> ? E : F;
206
190
 
207
191
  /**
208
- * @description The interface of adapter constructor with configurable async mode.
192
+ * @description Type to infer the element type from collection settings or adapter, with special handling for common collection types like Set, Array, and Map.
209
193
  * @export
210
- * @interface ConfigurableCollectionAdapterConstructor
211
- * @template E Elements type of `T`.
212
- * @template T Value type under which the elements are stored.
213
- * @template {CollectionSettings<E, T, any>} [C=CollectionSettings<E, T, any>]
214
- * @template {CollectionAdapter<E, T, C['async']>} [A=CollectionAdapter<E, T, C['async']>]
194
+ * @template C The collections configuration type to infer the element type from.
195
+ * @template [F=unknown] The fallback type to use if the element type cannot be inferred from either the collection settings or the adapter.
215
196
  */
216
- 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']>> {
217
- new (settings: C, ...elements: E[]): A;
218
- }
197
+ type InferElement<C, I = undefined, F = unknown> = InferElementFromSettings<C, F> extends F ? I extends CollectionShape<any, infer E, any> ? E : F : InferElementFromSettings<C, F>;
219
198
 
220
- export type { CollectionAdapter, CollectionAdapterConstructor, CollectionConstructor, CollectionSettings, CollectionShape, ConfigurableCollectionAdapterConstructor };
199
+ export type { CollectionAdapter, CollectionAdapterConstructor, CollectionConstructor, CollectionSettings, CollectionShape, InferCollectionType, InferElement, InferElementFromSettings };