Merge pull request #8 from objectwow/dev

Merge to main

Author: vtuanjs

README.md

@@ -12,28 +12,107 @@ In a microservices system where each service owns its own database, querying dat
 npm i @objectwow/join
 ```
 
-## Basic usage
+## Usage
 
 ```typescript
 import { joinData } from "@objectwow/join";
 
-const local = [
-  { id: 1, items: [101, 102] },
-  { id: 2, items: [201] },
+const orders = [
+  {
+    id: 1,
+    code: "1",
+    fulfillments: [
+      {
+        id: 11,
+        code: "11",
+        products: [
+          {
+            id: 111,
+            quantity: 1,
+          },
+          {
+            id: 112,
+            quantity: 4,
+          },
+        ],
+      },
+      {
+        id: 12,
+        code: "12",
+        products: [
+          {
+            id: 111,
+            quantity: 8,
+          },
+        ],
+      },
+    ],
+  },
+  {
+    id: 2,
+    code: "2",
+    fulfillments: [
+      {
+        id: 21,
+        code: "21",
+        products: [
+          {
+            id: 111,
+            quantity: 9,
+          },
+          {
+            id: 112,
+            quantity: 7,
+          },
+        ],
+      },
+      {
+        id: 22,
+        code: "22",
+        products: [
+          {
+            id: 111,
+            quantity: 2,
+          },
+          {
+            id: 112,
+            quantity: 3,
+          },
+        ],
+      },
+    ],
+  },
 ];
 
-const from = () => [
-  { id: 101, product: "Product 101" },
-  { id: 102, product: "Product 102" },
-  { id: 201, product: "Product 201" },
+const products = () => [
+  {
+    id: 111,
+    name: "Product 1",
+    price: 10,
+  },
+  {
+    id: 112,
+    name: "Product 2",
+    price: 20,
+  },
+  {
+    id: 113,
+    name: "Product 3",
+    price: 30,
+  },
 ];
 
 const result = await joinData({
-  local,
-  localField: "items",
-  from,
+  local: orders,
+  from: () => products,
+  localField: "fulfillments.products.id",
   fromField: "id",
-  as: "products",
+  as: "fulfillments.products",
+  asMap: {
+    id: "id",
+    name: "name",
+    price: "price",
+  },
 });
 ```
 
@@ -43,16 +122,44 @@ LocalData will be overwritten
 local = [
   {
     id: 1,
-    items: [101, 102],
-    products: [
-      { id: 101, product: "Product 101" },
-      { id: 102, product: "Product 102" },
+    code: "1",
+    fulfillments: [
+      {
+        id: 11,
+        code: "11",
+        products: [
+          { id: 111, name: "Product 1", price: 10, quantity: 1 },
+          { id: 112, name: "Product 2", price: 20, quantity: 4 },
+        ],
+      },
+      {
+        id: 12,
+        code: "12",
+        products: [{ id: 111, name: "Product 1", price: 10, quantity: 8 }],
+      },
     ],
   },
   {
     id: 2,
-    items: [201],
-    products: [{ id: 201, product: "Product 201" }],
+    code: "2",
+    fulfillments: [
+      {
+        id: 21,
+        code: "21",
+        products: [
+          { id: 111, name: "Product 1", price: 10, quantity: 9 },
+          { id: 112, name: "Product 2", price: 20, quantity: 7 },
+        ],
+      },
+      {
+        id: 22,
+        code: "22",
+        products: [
+          { id: 111, name: "Product 1", price: 10, quantity: 2 },
+          { id: 112, name: "Product 2", price: 20, quantity: 3 },
+        ],
+      },
+    ],
   },
 ];
 
@@ -62,53 +169,66 @@ result = {
 };
 ```
 
-Note: see more samples in the [`tests`](https://github.com/objectwow/join/blob/main/tests/core.spec.ts) and ['test-by-cases](https://github.com/objectwow/join/blob/main/test-by-cases)
+Note: see more samples in the [`tests`](https://github.com/objectwow/join/blob/main/tests/core.spec.ts) and [`test-by-cases`](https://github.com/objectwow/join/blob/main/test-by-cases)
 
 ```typescript
+/**
+ * Parameters for the `joinData` function to perform joins between local data and source data.
+ */
 export interface JoinDataParam {
   /**
-   * Local object or an array of local objects to be joined.
+   * Local object or array of local objects to be joined.
    */
   local: LocalParam;
 
   /**
-   * A callback (async) function that returns the data from the source.
-   * Data is object or an array of objects
+   * Object(s) or an asynchronous callback function that returns the data from the source.
    */
-  from: (...args: any[]) => any;
+  from: FromParam;
 
   /**
-   * The field name in the local object(s) used for the join,
-   * can be a nested field, separated by a dot ('.')
+   * Field name in the local object(s) used for the join.
    */
   localField: string;
 
   /**
-   * The field name in the from object used for the join,
-   * can be a nested field, separated by a dot ('.')
+   * Field name in the `from` object(s) used for the join.
    */
   fromField: string;
 
   /**
-   * An optional new field name to store the result of the join in the local object(s).
+   * Optional new field name to store the result of the join in the local object(s).
    */
   as?: string;
 
   /**
-   * An optional mapping from the from object(s) values to the new field names in the local object(s).
+   * Optional mapping from the `fromField` values to new field names in the local object(s).
    */
   asMap?: AsMap;
 }
 
-export type LocalParam = object | object[];
-
-export type AsMap = { [key: string]: string };
+export type FromParam =
+  | ((localFieldValues: Primitive[], metadata: any) => any)
+  | object
+  | object[];
 
-export type JoinDataResult =
-  | { joinFailedValues: Primitive[]; allSuccess: boolean }
-  | any;
+export type AsMap =
+  | ((currentFrom: any, currentLocal: any, metadata: any) => any)
+  | { [key: string]: string }
+  | string;
 ```
 
+## Test
+
+`npm run test` or `npm run test:cov`
+
+| File         | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s                    |
+| ------------ | ------- | -------- | ------- | ------- | ------------------------------------ |
+| All files    | 93      | 78.68    | 95.23   | 92.8    |                                      |
+| core.ts      | 90.82   | 73.17    | 100     | 90.82   | 18,42,53,106,128,141,163,206,247,251 |
+| singleton.ts | 100     | 100      | 75      | 100     |                                      |
+| util.ts      | 100     | 89.47    | 100     | 100     | 23-24                                |
+
 ## Customization
 
 With an out-of-the-box design, you can create your own function using the current structure.
@@ -117,32 +237,16 @@ With an out-of-the-box design, you can create your own function using the curren
 import { JoinData } from "@objectwow/join";
 
 export class YourJoin extends JoinData {
-  public execute(
-    param: JoinDataParam,
-    metadata?: any
-  ): Promise<JoinDataResult> {}
-
   // Use case: Currently, deep values are split by a dot ('.'), but you can use a different symbol if needed
   protected separateSymbol: string;
 
-  protected generateAsValue(param: GenerateAsValueParam) {}
-
   // Use case: Return your custom output
   protected generateResult(
     joinFailedValues: Primitive[],
     localOverwrite: LocalParam,
     metadata?: any
   ) {}
 
-  protected getFieldValue(parent: object, path: string) {}
-
-  protected handleLocalObj(param: HandleLocalObjParam): void {}
-
-  protected parseFieldPath(fieldPath: string): {
-    path: string;
-    newPath: string;
-  } {}
-
   // Use case: Shadow clone local data without overwriting the original.
   protected standardizeLocalParam(
     local: LocalParam,
@@ -152,6 +256,7 @@ export class YourJoin extends JoinData {
   // Use case: Automatically call internal or external services to retrieve data based on the input
   protected standardizeFromParam(
     from: FromParam,
+    localFieldValues: string[],
     metadata?: any
   ): Promise<any[]> {}
 
@@ -199,11 +304,45 @@ await joinCls.execute({...})
 
 Tips:
 
-- You can call original function (parent function) with `super.`
+- You can call original function (parent function) with `super.
 - You can pass anything to the metadata
 
 ## Benchmark
 
-- Execute: `node lib/benchmark.js`
-- Report: JoinData Execution x 2,289,754 ops/sec ±3.38% (86 runs sampled)
-- Device: MacbookPro M1, 16 GB RAM, 12 CPU
+- Source:
+
+```typescript
+// Generate localData with 100 orders and 2 fulfillments per order
+const localData = Array.from({ length: 100 }, (_, i) => ({
+  id: i + 1, // Order ID starting from 1
+  code: `${i + 1}`, // Order code
+  fulfillments: Array.from({ length: 2 }, (_, j) => ({
+    id: (i + 1) * 10 + j, // Fulfillment ID for each order
+    code: `${(i + 1) * 10 + j}`, // Fulfillment code
+    products: Array.from({ length: 2 }, () => {
+      const productId = Math.floor(Math.random() * 100) + 111; // Random product ID between 111 and 210
+      return {
+        id: productId,
+        quantity: Math.floor(Math.random() * 10) + 1, // Random quantity between 1 and 10
+      };
+    }),
+  })),
+}));
+
+// Generate fromData with 100 products
+const fromData = Array.from({ length: 100 }, (_, i) => ({
+  id: i + 111, // IDs starting from 111
+  name: `Product ${i + 1}`,
+  price: Math.floor(Math.random() * 100 + 1), // Random price between 1 and 100
+}));
+```
+
+- Execute: `node lib/benchmark.js` (need build first)
+- Report: JoinData Execution x 125,972 ops/sec ±1.27% (66 runs sampled)
+- Device: Macbook Pro M1 Pro, 16 GB RAM, 12 CPU
+
+## Contributors
+
+If you have any questions, feel free to open an [`open an issue on GitHub`](https://github.com/objectwow/join/issues) or connect with me on [`Linkedin`](https://www.linkedin.com/in/vtuanjs/).
+
+Thank you for using and supporting the project!

benchmark.ts

@@ -5,21 +5,44 @@ import { joinData } from "./index"; // Import your core function/module
 
 const suite = new Benchmark.Suite();
 
-// Example input data
-const localData = { id: 1, name: "LocalName" };
-const fromData = [{ id: 1, name: "Alice", age: 25 }];
+const localData = Array.from({ length: 100 }, (_, i) => ({
+  id: i + 1, // Order ID starting from 1
+  code: `${i + 1}`, // Order code
+  fulfillments: Array.from({ length: 2 }, (_, j) => ({
+    id: (i + 1) * 10 + j, // Fulfillment ID for each order
+    code: `${(i + 1) * 10 + j}`, // Fulfillment code
+    products: Array.from({ length: 2 }, () => {
+      const productId = Math.floor(Math.random() * 100) + 111; // Random product ID between 111 and 210
+      return {
+        id: productId,
+        quantity: Math.floor(Math.random() * 10) + 1, // Random quantity between 1 and 10
+      };
+    }),
+  })),
+}));
+
+// Generate fromData with 100 products
+const fromData = Array.from({ length: 100 }, (_, i) => ({
+  id: i + 111, // IDs starting from 111
+  name: `Product ${i + 1}`,
+  price: Math.floor(Math.random() * 100 + 1), // Random price between 1 and 100
+}));
 
 // Add your benchmarks
 suite
   .add("JoinData Execution", () => {
     // Call the method you want to benchmark
     joinData({
-      local: localData,
-      from: () => fromData,
-      localField: "id",
+      local: JSON.parse(JSON.stringify(localData)),
+      from: fromData,
+      localField: "fulfillments.products.id",
       fromField: "id",
-      asMap: undefined,
-      as: "from",
+      as: "fulfillments.products",
+      asMap: {
+        id: "id",
+        name: "name",
+        price: "price",
+      },
     });
   })
   .on("cycle", (event: any) => {