@typedly/data 1.0.0 → 3.0.0

package/README.md

@@ -16,15 +16,27 @@
 
 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)
 - [Code of Conduct](#code-of-conduct)
@@ -53,23 +65,112 @@ npm install @typedly/data --save-peer
 ```typescript
 import {
   // Interface.
+  DataAdapter,
   DataConstructor,
   DataShape,
+  ValueConstructor,
+  ValueShape,
   // Type.
-  DataConstructorInput
+  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.
 
 ```typescript
-import { DataConstructor } from '@typedly/data';
+import { DataConstructor, DataShape } from '@typedly/data';
+
+// Import DataShape and DataConstructor.
+// Create a data class that implements `DataShape` of `Type`.
+export class ProfileData<
+  Value extends { age: number, name: string }
+> implements DataShape<Value> {
+
+  get value(): Value {
+    return {
+      age: this.#age,
+      name: this.#name
+    } as Value;
+  }
+
+  #age;
+  #name;
+  constructor(value: Value, ...args: any[]) {
+    console.log(`Instantiated DataConstructor`, value, ...args);
+    this.#age = value.age;
+    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;
+  }
+}
+
+// Create `ProfileClass` with customizable data.
+export class ProfileClass<
+  Value extends { age: number, name: string },
+  DataType extends DataShape<Value>,
+  Args extends any[]
+> {
+
+  public get age(): Value['age'] {
+    return this.#data.value.age;
+  }
+
+  public get name(): Value['name'] {
+    return this.#data.value.name;
+  }
+
+  public get data() {
+    return this.#data;
+  }
+
+  #data: DataType;
+
+  constructor(value: Value, dataCtor: DataConstructor<Value, DataType>);
+  constructor(value: Value, dataCtor: [DataConstructor<Value, DataType>, ...Args]);
+  constructor(value: Value, dataCtor: any) {
+    // ...implementation
+    console.log(`DataConstructor`, value, dataCtor[1]);
+    this.#data = Array.isArray(dataCtor)
+      ? new dataCtor[0](value, ...dataCtor.slice(1))
+      : new dataCtor(value);
+  }
+}
+
+// Initialize.
+// const frankProfile: ProfileClass<object, ProfileData<object>, any[]>
+const frankProfile = new ProfileClass({ age: 37, name: 'Frank' }, ProfileData);
 
-export const ctor: DataConstructor<number, DataShape<number>, any[]> = TestData;
+frankProfile.age; // 37
+frankProfile.name; // Frank
+
+// Set the data.
+frankProfile.data.set({ age: 37, name: 'Frank' });
+frankProfile.data.clear();
+frankProfile.data.lock();
+frankProfile.data.value;
 ```
 
 [Source](https://github.com/typedly/data/blob/main/src/lib/interface/data-constructor.interface.ts)
@@ -93,30 +194,184 @@ class TestData implements DataShape<number> {
 
 [Source](https://github.com/typedly/data/blob/main/src/lib/interface/data-shape.interface.ts)
 
+#### `ValueConstructor`
+
+```typescript
+import { ValueConstructor } from '@typedly/data';
+```
+
+[Source](https://github.com/typedly/data/blob/main/src/lib/interface/value-constructor.interface.ts)
+
+#### `ValueShape`
+
+The shape of a `Value` type.
+
+```typescript
+import { ValueShape } from '@typedly/data';
+```
+
+[Source](https://github.com/typedly/data/blob/main/src/lib/interface/value-shape.interface.ts)
+
 ### 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.
 
 ```typescript
-import { DataConstructorInput, DataShape } from '@typedly/data';
-
-function createData<Value, DataType extends DataShape<Value>>(
-  input: DataConstructorInput<Value, DataType>,
-  value: Value
-): DataType {
-  if (Array.isArray(input)) {
-    const [Ctor, ...args] = input;
-    return new Ctor(value, ...args);
-  } else {
-    return new input(value);
-  }
-}
+import { DataConstructorInput } from '@typedly/data';
 ```
 
 [Source](https://github.com/typedly/data/blob/main/src/lib/type/data-constructor-input.type.ts)
 
+#### `DataConstructorTuple`
+
+The input type for data constructors, with arguments support.
+
+```typescript
+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
+import { DataConstructor, DataShape, ValueConstructor, ValueShape } from '@typedly/data';
+
+// Import ValueShape and ValueConstructor.
+// Create a profile data value.
+export class ProfileDataValue<
+  Type extends { age: number, name: string },
+  Args extends any[] = any[]
+> implements ValueShape<Type> {
+  get value(): Type {
+    return {
+      age: this.#age,
+      name: this.#name
+    } as Type;
+  }
+
+  #age: Type['age'];
+  #name: Type['name'];
+
+  constructor(value: Type, ...args: Args) {
+    console.log(`Instantiated ValueConstructor`, value, ...args);
+    this.#age = value.age;
+    this.#name = value.name;
+  }
+
+  set(value: Type): this { return this; }
+}
+
+export class ProfileDataOfValue<
+  Value extends { age: number, name: string },
+  Args extends any[] = any[],
+  ValueInstance extends ValueShape<Value> = ProfileDataValue<Value, Args>,
+> implements DataShape<Value> {
+
+  get value(): Value {
+    return {
+    } as Value;
+  }
+
+  get valueInstance(): ValueInstance {
+    return this.#value;
+  }
+
+  #value;
+  constructor(
+    value: Value,
+    valueCtor: ValueConstructor<Value, ValueInstance, Args> = ProfileDataValue<Value, Args> as any,
+    ...args: Args
+  ) {
+    console.log(`Instantiated DataConstructor`, value, ...args);
+    this.#value = new valueCtor(value, ...args);
+  }
+
+  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;
+  }
+}
+
+// const profileDataOfValue: ProfileDataOfValue<{
+//     age: number;
+//     name: string;
+// }, ProfileDataValue<{
+//     age: number;
+//     name: string;
+// }, []>, []>
+const profileDataOfValue = new ProfileDataOfValue({
+  age: 37,
+  name: 'Mark'
+}, ProfileDataValue);
+
+const dataSymbol = Symbol('data');
+
+// Create `ProfileClass` with customizable data.
+export class ProfileClass<
+  Value extends { age: number, name: string },
+  DataType extends DataShape<Value>,
+  Args extends any[]
+> {
+
+  public get age(): Value['age'] {
+    return this.#data.value.age;
+  }
+
+  public get name(): Value['name'] {
+    return this.#data.value.name;
+  }
+
+  public get [dataSymbol]() {
+    return this.#data;
+  }
+
+  #data: DataType;
+
+  constructor(value: Value, dataCtor: DataConstructor<Value, DataType, Args>);
+  constructor(value: Value, dataCtor: [DataConstructor<Value, DataType, Args>, ...Args]);
+  constructor(value: Value, dataCtor: any) {
+    // ...implementation
+    console.log(`DataConstructor`, value, dataCtor[1]);
+    this.#data = Array.isArray(dataCtor)
+      ? new dataCtor[0](value, ...dataCtor.slice(1))
+      : new dataCtor(value);
+  }
+}
+
+const markProfile = new ProfileClass({ age: 37, name: 'Mark' }, ProfileDataOfValue);
+
+markProfile.age // 37
+markProfile.name // Mark
+markProfile[dataSymbol].value // { age, name }
+markProfile[dataSymbol].valueInstance.set({ age: 27, name: 'Frank' });
+```
+
 ## Contributing
 
 Your contributions are valued! If you'd like to contribute, please feel free to submit a pull request. Help is always appreciated.
@@ -209,7 +464,7 @@ MIT © typedly ([license][typedly-license])
 
 <!-- Package: typedly -->
   <!-- npm -->
-  [typedly-npm-badge-svg]: https://badge.fury.io/js/@typedly%2Fdata.svg
+  [typedly-npm-badge-svg]: https://badge.fury.io/gh/typedly%2Fdata.svg
   [typedly-npm-badge]: https://badge.fury.io/js/@typedly%2Fdata
 
 <!-- GIT -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typedly/data",
-  "version": "1.0.0",
+  "version": "3.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/types/typedly-data.d.ts

@@ -0,0 +1,101 @@
+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 T The value type.
+ * @template {boolean} [Async=false] The `Promise` return type for methods.
+ */
+interface DataShape<T, Async extends boolean = false> {
+    value: T;
+    clear(): AsyncReturn<Async, this>;
+    destroy(): AsyncReturn<Async, this>;
+    lock(): this;
+    set(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;
+}
+
+/**
+ * @description The constructor interface for data types.
+ * @export
+ * @interface DataConstructor
+ * @template Value
+ * @template {DataShape<Value>} Instance The instance.
+ * @template {readonly any[]} [Args=any[]]
+ * @extends {BaseDataConstructor<Value, DataShape<Value>, Instance, [...Args]>}
+ */
+interface DataConstructor<Value, Instance extends DataShape<Value>, Args extends readonly any[] = any[]> extends DataConstructor$1<Value, DataShape<Value>, Instance, [...Args]> {
+}
+
+/**
+ * @description The value shape.
+ * @export
+ * @interface ValueShape
+ * @template Type The type of value.
+ */
+interface ValueShape<Type> {
+    get value(): Type;
+    set(value: Type): this;
+}
+
+/**
+ * @description The constructor for value in data for advanced customization.
+ * @export
+ * @interface ValueConstructor
+ * @template Value The value type.
+ * @template {ValueShape<Value>} Instance The instance.
+ * @template {readonly any[]} [Args=any[]] Additional arguments passed to the constructor.
+ * @extends {BaseDataConstructor<Value, ValueShape<Value>, Instance, [...Args]>}
+ */
+interface ValueConstructor<Value, Instance extends ValueShape<Value>, Args extends readonly any[] = any[]> extends DataConstructor$1<Value, ValueShape<Value>, Instance, [...Args]> {
+}
+
+export type { AsyncReturn, DataAdapter, DataConstructor, DataConstructorInput, DataConstructorTuple, DataShape, IterValue, ValueConstructor, ValueShape };

package/index.d.ts

@@ -1,37 +0,0 @@
-import { DataConstructor as DataConstructor$1 } from '@typedly/constructor';
-
-/**
- * @description The shape of a `Data` type.
- * @export
- * @interface DataShape
- * @template Value The value type.
- */
-interface DataShape<Value> {
-    get value(): Value;
-    clear(): this;
-    destroy(): this;
-    lock(): this;
-    set(value: Value): this;
-}
-
-/**
- * @description The constructor interface for data types.
- * @export
- * @interface DataConstructor
- * @template Value
- * @template {DataShape<Value>} Instance The instance.
- * @template {readonly any[]} [Args=any[]]
- * @extends {BaseDataConstructor<Value, DataShape<Value>, Instance, [...Args]>}
- */
-interface DataConstructor<Value, Instance extends DataShape<Value>, Args extends readonly any[] = any[]> extends DataConstructor$1<Value, DataShape<Value>, Instance, [...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.
- */
-type DataConstructorInput<Value, Instance extends DataShape<Value>> = [DataConstructor<Value, Instance>, ...any[]] | DataConstructor<Value, Instance>;
-
-export type { DataConstructor, DataConstructorInput, DataShape };