{"id":17122015,"url":"https://github.com/objectwow/join","last_synced_at":"2025-04-13T05:01:39.646Z","repository":{"id":257821296,"uuid":"870116519","full_name":"objectwow/join","owner":"objectwow","description":"Perform a deep join of arrays of objects using UIDs","archived":false,"fork":false,"pushed_at":"2024-10-26T16:08:51.000Z","size":154,"stargazers_count":19,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-26T05:07:39.338Z","etag":null,"topics":["array","deep","javascript","join","merge","nodejs","object","open-source","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@objectwow/join","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/objectwow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-09T13:23:40.000Z","updated_at":"2024-10-26T17:43:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"c3a53108-c299-4d39-b1ad-b334b53f67cc","html_url":"https://github.com/objectwow/join","commit_stats":null,"previous_names":["objectwow/join"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/objectwow%2Fjoin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/objectwow%2Fjoin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/objectwow%2Fjoin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/objectwow%2Fjoin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/objectwow","download_url":"https://codeload.github.com/objectwow/join/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665755,"owners_count":21142123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["array","deep","javascript","join","merge","nodejs","object","open-source","typescript"],"created_at":"2024-10-14T18:06:10.357Z","updated_at":"2025-04-13T05:01:39.609Z","avatar_url":"https://github.com/objectwow.png","language":"TypeScript","readme":"# @objectwow/join\n\nPerform a deep join of arrays of objects using UIDs.\n\n⭐️ Your star shines on us. Star us on [GitHub](https://github.com/objectwow/join)!\n\n# Use case\n\nWhen you aggregate data, such as orders and products, you might have something like the following example:\n\n```typescript\nconst orders = [\n  {\n    id: 1,\n    code: \"1\",\n    fulfillments: [\n      {\n        id: 12,\n        code: \"12\",\n        products: [{ id: 111, quantity: 8 }],\n      },\n      {\n        id: 13,\n        code: \"13\",\n        products: [{ id: 112, quantity: 10 }],\n      },\n    ],\n  },\n];\n\nconst products = [\n  { id: 111, name: \"Product 1\", price: 10 },\n  { id: 112, name: \"Product 2\", price: 20 },\n];\n```\n\n- Add `name`, `price` to `fulfillments.products`\n\n```typescript\norders = [\n  {\n    id: 1,\n    code: \"1\",\n    fulfillments: [\n      {\n        id: 12,\n        code: \"12\",\n        products: [{ id: 111, name: \"Product 1\", price: 10, quantity: 8 }],\n      },\n      // another data\n    ],\n  },\n];\n```\n\n- Add `product` to `fulfillments.products`\n\n```typescript\norders = [\n  {\n    id: 1,\n    code: \"1\",\n    fulfillments: [\n      {\n        id: 12,\n        code: \"12\",\n        products: [\n          {\n            id: 111,\n            quantity: 8,\n            product: {\n              id: 111,\n              name: \"Product 1\",\n              price: 10,\n            },\n          },\n        ],\n      },\n      // another data\n    ],\n  },\n];\n```\n\n- Add `productNames` to root\n\n```typescript\norders = [\n  {\n    id: 1,\n    code: \"1\",\n    productNames: [\"Product 1\", \"Product 2\"],\n    // another data\n  },\n];\n```\n\n- Add `productNameWithPrices` to root\n\n```typescript\norders = [\n  {\n    id: 1,\n    code: \"1\",\n    productNameWithPrices: [\"Product 1 10\", \"Product 2 20\"],\n    // another data\n  },\n];\n```\n\nWe need a library to simplify this process.\n\n# Installation\n\n```\nnpm i @objectwow/join\n```\n\n# Usage\n\n```typescript\nimport { joinData } from \"@objectwow/join\";\n\nconst result = await joinData({\n  local: orders,\n  from: products,\n  localField: \"fulfillments.products.id\",\n  fromField: \"id\",\n  as: \"fulfillments.products\",\n});\n```\n\nLocalData (orders) will be overwritten. Order products will have the `name` and `price` fields.\n\n```typescript\norders = [\n  {\n    id: 1,\n    code: \"1\",\n    fulfillments: [\n      {\n        id: 12,\n        code: \"12\",\n        products: [{ id: 111, name: \"Product 1\", price: 10, quantity: 8 }],\n      },\n      {\n        id: 13,\n        code: \"13\",\n        products: [{ id: 112, name: \"Product 2\", price: 20, quantity: 10 }],\n      },\n    ],\n  },\n];\n\nresult = {\n  allSuccess: true,\n  joinFailedValues: [],\n};\n```\n\nNote: 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)\n\n# Parameters\n\n```typescript\n/**\n * Parameters for the `joinData` function to perform joins between local data and source data.\n */\nexport interface JoinDataParam {\n  /**\n   * Local object or array of local objects to be joined.\n   */\n  local: LocalParam;\n\n  /**\n   * Objects or an asynchronous callback function that returns the data from the source.\n   */\n  from: FromParam;\n\n  /**\n   * Field name in the local object(s) used for the join.\n   */\n  localField: string;\n\n  /**\n   * Field name in the `from` object(s) used for the join.\n   */\n  fromField: string;\n\n  /**\n   * Optional new field name to store the result of the join in the local object(s).\n   */\n  as?: string;\n\n  /**\n   * Optional mapping from the `fromField` values to new field names in the local object(s).\n   */\n  asMap?: AsMap;\n}\n\nexport type LocalParam = object | object[];\n\nexport type FromParam =\n  | ((localFieldValues: Primitive[], metadata: any) =\u003e object[])\n  | object[];\n\nexport type AsMap =\n  | ((currentFrom: any, currentLocal: any, metadata: any) =\u003e any)\n  | { [key: string]: string }\n  | string;\n```\n\n# Internal resources\n\n- [Comparison](COMPARISON.md)\n- [Testing](TESTING.md)\n- [Benchmark](BENCHMARK.md)\n- [Customization](CUSTOMIZATION.md)\n- [Question](QUESTION.md)\n\n# Contact\n\nIf 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/).\n\nThank you for using and supporting the project!\n\n# Contributors\n\n\u003ca href=\"https://github.com/objectwow/join/graphs/contributors\"\u003e\u003cimg src=\"https://opencollective.com/objectwow-join/contributors.svg?width=882\u0026button=false\" /\u003e\u003c/a\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobjectwow%2Fjoin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobjectwow%2Fjoin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobjectwow%2Fjoin/lists"}