@typedly/data 2.0.0 → 4.0.0

package/README.md

@@ -16,18 +16,26 @@
 
 A **TypeScript** type definitions package for [**@typescript-package/data**](https://github.com/typescript-package/data).
 
+## Features
+
+- **Adapter**: Optional data adapter to customize managing underlying data.
+- **Shape**: The default shape for data of any `T` type with conditional async.
+
 ## Table of contents
 
 - [Installation](#installation)
 - [Api](#api)
   - [Interface](#interface)
+    - [`DataAdapter`](#dataadapter)
     - [`DataConstructor`](#dataconstructor)
     - [`DataShape`](#datashape)
     - [`ValueConstructor`](#valueconstructor)
     - [`ValueShape`](#valueshape)
   - [Type](#type)
+    - [`AsyncReturn`](#asyncreturn)
     - [`DataConstructorInput`](#dataconstructorinput)
     - [`DataConstructorTuple`](#dataconstructortuple)
+    - [`IterValue`](#itervalue)
 - [Full example usage](#full-example-usage)
 - [Contributing](#contributing)
 - [Support](#support)
@@ -57,18 +65,31 @@ npm install @typedly/data --save-peer
 ```typescript
 import {
   // Interface.
+  DataAdapter,
   DataConstructor,
   DataShape,
   ValueConstructor,
   ValueShape,
   // Type.
+  AsyncReturn,
   DataConstructorInput,
   DataConstructorTuple,
+  IterValue
 } from '@typedly/data';
 ```
 
 ### Interface
 
+#### `DataAdapter`
+
+The adapter interface for data types.
+
+```typescript
+import { DataAdapter } from '@typedly/data';
+```
+
+[Source](https://github.com/typedly/data/blob/main/src/lib/interface/data-adapter.interface.ts)
+
 #### `DataConstructor`
 
 The constructor interface for data types.
@@ -82,7 +103,7 @@ export class ProfileData<
   Value extends { age: number, name: string }
 > implements DataShape<Value> {
 
-  get value(): Value {
+  public get value(): Value {
     return {
       age: this.#age,
       name: this.#name
@@ -97,13 +118,12 @@ export class ProfileData<
     this.#name = value.name;
   }
 
-  set(value: Value): this { this.validate(value); return this; }
-  clear(): this { return this; }
-  destroy(): this { return this; }
-  lock(): this { return this; };
-  validate(value: Value): boolean {
-    return true;
-  }
+  public clear(): this { return this; }
+  public destroy(): this { return this; }
+  public lock(): this { return this; };
+  public getValue(): Value { return this.value; }
+  public setValue(value: Value): this { this.validate(value); return this; }
+  public validate(value: Value): boolean { return true; }
 }
 
 // Create `ProfileClass` with customizable data.
@@ -146,10 +166,16 @@ frankProfile.age; // 37
 frankProfile.name; // Frank
 
 // Set the data.
-frankProfile.data.set({ age: 37, name: 'Frank' });
+frankProfile.data.setValue({ age: 37, name: 'Frank' });
 frankProfile.data.clear();
 frankProfile.data.lock();
 frankProfile.data.value;
+
+// Initialize with arguments.
+const markProfile = new ProfileClass(
+  { age: 27, name: 'Mark' },
+  [ProfileData, 'private', true]
+);
 ```
 
 [Source](https://github.com/typedly/data/blob/main/src/lib/interface/data-constructor.interface.ts)
@@ -161,13 +187,17 @@ The shape of a `Data` type.
 ```typescript
 import { DataShape } from '@typedly/data';
 
-class TestData implements DataShape<number> {
-  get value(): number { return this.initialValue; }
-  constructor(private initialValue: number) {}
-  public clear(): this { return this; }
-  public destroy(): this { return this; }
-  public lock(): this { return this; }
-  public set(value: number): this { return this; }
+// Create a simple data class with value as property.
+export class TestData<Type> implements DataShape<Type> {
+  get value(): Type { return 27 as Type; }
+  clear(): this { return this; }
+  destroy(): this { return this; }
+  getValue(): Type { return 27 as Type; }
+  lock(): this { return this; };
+  setValue(value: Type): this { return this; }
+  constructor(value: Type, ...args: any[]) {
+    console.log(`Instantiated DataConstructor`, value, ...args);
+  }
 }
 ```
 
@@ -193,6 +223,16 @@ import { ValueShape } from '@typedly/data';
 
 ### Type
 
+#### `AsyncReturn`
+
+The conditional return type for async methods.
+
+```typescript
+import { AsyncReturn } from '@typedly/data';
+```
+
+[Source](https://github.com/typedly/data/blob/main/src/lib/type/async-return.type.ts)
+
 #### `DataConstructorInput`
 
 The input type for data constructors, with arguments support.
@@ -213,6 +253,16 @@ import { DataConstructorTuple } from '@typedly/data';
 
 [Source](https://github.com/typedly/data/blob/main/src/lib/type/data-constructor-tuple.type.ts)
 
+#### `IterValue`
+
+The iterated value type.
+
+```typescript
+import { IterValue } from '@typedly/data';
+```
+
+[Source](https://github.com/typedly/data/blob/main/src/lib/type/iter-value.type.ts)
+
 ### Full example usage
 
 ```typescript
@@ -268,7 +318,10 @@ export class ProfileDataOfValue<
     this.#value = new valueCtor(value, ...args);
   }
 
-  set(value: Value): this { this.validate(value); return this; }
+  setValue(value: Value): this { this.validate(value); return this; }
+  getValue(): Value {
+    return this.#value.value;
+  }
   clear(): this { return this; }
   destroy(): this { return this; }
   lock(): this { return this; };
@@ -342,10 +395,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/data",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "author": "wwwdev.io <dev@wwwdev.io>",
   "description": "A TypeScript type definitions package for @typescript-package/data.",
   "license": "MIT",
@@ -33,13 +33,13 @@
     }
   ],
   "sideEffects": false,
-  "typings": "index.d.ts",
+  "typings": "types/typedly-data.d.ts",
   "exports": {
     "./package.json": {
       "default": "./package.json"
     },
     ".": {
-      "types": "./index.d.ts",
+      "types": "./types/typedly-data.d.ts",
       "default": "./fesm2022/typedly-data.mjs"
     }
   }

package/{index.d.ts → types/typedly-data.d.ts}

@@ -1,17 +1,67 @@
 import { DataConstructor as DataConstructor$1 } from '@typedly/constructor';
 
+/**
+ * @description The conditional return type for async methods.
+ * @export
+ * @template Async The boolean flag indicating if the return type should be a Promise.
+ * @template T The type of the value to be returned.
+ */
+type AsyncReturn<Async, T> = Async extends true ? Promise<T> : T;
+
+/**
+ * @description The type to provide data constructor with arguments.
+ * @export
+ * @template Value The value type.
+ * @template {DataShape<Value>} Instance The shape of the instance.
+ * @template {any[]} [Args=any[]] Additional Arguments passed to the instance.
+ */
+type DataConstructorTuple<Value, Instance extends DataShape<Value>, Args extends any[] = any[]> = [DataConstructor<Value, Instance, Args>, ...Args];
+
+/**
+ * @description The input type for data constructors, with arguments support.
+ * @export
+ * @template Value The value type.
+ * @template {DataShape<Value>} Instance The data instance type.
+ * @template {any[]} [Args=any[]] The arguments to pass to instance.
+ */
+type DataConstructorInput<Value, Instance extends DataShape<Value>, Args extends any[] = any[]> = DataConstructor<Value, Instance, Args> | DataConstructorTuple<Value, Instance, Args>;
+
+/**
+ * @description The iterated value type.
+ * @export
+ * @template T The type of iterated value constrained by the `Iterable` type.
+ */
+type IterValue<T> = T extends Iterable<infer U> ? U : T;
+
 /**
  * @description The shape of a `Data` type.
  * @export
  * @interface DataShape
- * @template Value The value type.
+ * @template T The value type.
+ * @template {boolean} [Async=false] The `Promise` return type for methods.
  */
-interface DataShape<Value> {
-    get value(): Value;
-    clear(): this;
-    destroy(): this;
+interface DataShape<T, Async extends boolean = false> {
+    value: T;
+    clear(): AsyncReturn<Async, this>;
+    destroy(): AsyncReturn<Async, this>;
+    getValue(): AsyncReturn<Async, T>;
     lock(): this;
-    set(value: Value): this;
+    setValue(value: T): AsyncReturn<Async, this>;
+    [Symbol.toStringTag]?: string;
+    [Symbol.iterator]?(): IterableIterator<IterValue<T>>;
+    [Symbol.asyncIterator]?(): AsyncIterableIterator<IterValue<T>>;
+}
+
+/**
+ * @description The adapter interface for data types.
+ * @export
+ * @interface DataAdapter
+ * @template T The type of the data value.
+ * @template {boolean} [R=false] The type of the return values for methods.
+ * @extends {DataShape<T, R>}
+ */
+interface DataAdapter<T, R extends boolean = false> extends DataShape<T, R> {
+    version?: string;
 }
 
 /**
@@ -49,22 +99,4 @@ interface ValueShape<Type> {
 interface ValueConstructor<Value, Instance extends ValueShape<Value>, Args extends readonly any[] = any[]> extends DataConstructor$1<Value, ValueShape<Value>, Instance, [...Args]> {
 }
 
-/**
- * @description The type to provide data constructor with arguments.
- * @export
- * @template Value The value type.
- * @template {DataShape<Value>} Instance The shape of the instance.
- * @template {any[]} [Args=any[]] Additional Arguments passed to the instance.
- */
-type DataConstructorTuple<Value, Instance extends DataShape<Value>, Args extends any[] = any[]> = [DataConstructor<Value, Instance, Args>, ...Args];
-
-/**
- * @description The input type for data constructors, with arguments support.
- * @export
- * @template Value The value type.
- * @template {DataShape<Value>} Instance The data instance type.
- * @template {any[]} [Args=any[]] The arguments to pass to instance.
- */
-type DataConstructorInput<Value, Instance extends DataShape<Value>, Args extends any[] = any[]> = DataConstructor<Value, Instance, Args> | DataConstructorTuple<Value, Instance, Args>;
-
-export type { DataConstructor, DataConstructorInput, DataConstructorTuple, DataShape, ValueConstructor, ValueShape };
+export type { AsyncReturn, DataAdapter, DataConstructor, DataConstructorInput, DataConstructorTuple, DataShape, IterValue, ValueConstructor, ValueShape };