relation-matcher 1.0.11 → 1.0.13

package/.yarnrc.yml

@@ -1 +1,3 @@
 nodeLinker: node-modules
+
+yarnPath: .yarn/releases/yarn-4.13.0.cjs

package/README.md

@@ -0,0 +1,150 @@
+# Relation Matcher
+
+This is a utility to convert unstructured data from a database into structured relational json data.
+
+## Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+    - [Data](#data)
+    - [Schema](#schema)
+    - [Output](#output)
+
+## Installation
+
+|      | Installation Command        |
+| ---- | --------------------------- |
+| npm  | `npm i relation-matcher`    |
+| yarn | `yarn add relation-matcher` |
+| pnpm | `pnpm add relation-matcher` |
+
+## Usage
+
+To use the relation matcher you feed in your `data` from your database and a `schema`. For example with drizzle:
+
+```ts
+import relationMatcher from "relation-matcher";
+import db from "~/db/client";
+
+/* Get your data from the database */
+const dbData = await db.select().fro...
+
+const data /* Output */ = relationMatcher(
+	dbData /* Data */,
+	{...} /* Schema */
+);
+
+return data;
+```
+
+### `data`
+
+The `data`'s shape should extend:
+
+```ts
+Array<Record<string, Record<string, unknown> | null>>;
+```
+
+#### Example
+
+The data could have the following type:
+
+```ts
+{
+	user: {
+		id: string;
+		email: string;
+		password: string;
+		...otherColumns
+	};
+
+	post: {
+		id: string;
+		title: string;
+		content: string;
+
+		author_id: string; // < Same as user.id
+	}
+}[]
+```
+
+### `schema`
+
+The `schema`'s shape should be:
+
+```ts
+{
+	base: "name of table",
+	id: "distinct column in above table",
+
+	_yourJoinedTableName: {
+		base: "name of table to join",
+		id: "distinct column of above table",
+		joinsFrom: "column of parent table",
+		joinsTo: "column of current table",
+		joinType: "single" | "array"
+	}
+}
+```
+
+> [!NOTE]
+> Keys for joins start with an underscore; the final property key will have the leading underscore removed.
+
+#### Example
+
+With the above `data`, the `schema`'s shape could be:
+
+```ts
+{
+	base: "user",
+	id: "id",
+
+	_posts: {
+		base: "post",
+		id: "id",
+		joinsFrom: "id",
+		joinsTo: "author_id",
+		joinType: "array",
+	}
+}
+```
+
+### `output`
+
+The outputted data will take the shape of your schema.
+
+#### Example
+
+For the `data` and `schema` provided above, the `output` will have the following type:
+
+```ts
+Record<
+	string, // The id specified in the root of your schema.
+	{
+		id: string;
+		email: string;
+		password: string;
+		...otherColumns;
+
+		posts: Array<
+			{
+				id: string;
+				title: string;
+				content: string;
+
+				author_id: string;
+			}
+		>;
+	}
+>;
+```
+
+## Changelog
+
+### 1.0.13
+
+- Added readme.
+
+### 1.0.12
+
+- Fixed type issue where return type would be repeated union of expected `output`.

package/dist/src/index.d.ts

@@ -1,7 +1,6 @@
 import type { TInputBase } from "./types/generic-bases";
 import type { RelationMapRoot } from "./types/inputs";
 import type { RelationMapperReturnRoot } from "./types/return";
-export declare const relationMatcher: <TInput extends TInputBase, TOutputRoot extends RelationMapRoot<TInput>>(inputs: TInput[], output: TOutputRoot) => Record<string, RelationMapperReturnRoot<TInput, TOutputRoot>>;
-/** @deprecated Use `relationMatcher`. */
 export declare const relationMatcherRoot: <TInput extends TInputBase, TOutputRoot extends RelationMapRoot<TInput>>(inputs: TInput[], output: TOutputRoot) => Record<string, RelationMapperReturnRoot<TInput, TOutputRoot>>;
-export default relationMatcher;
+export declare const relationMatcher: <TInput extends TInputBase, TOutputRoot extends RelationMapRoot<TInput>>(inputs: TInput[], output: TOutputRoot) => Record<string, RelationMapperReturnRoot<TInput, TOutputRoot>>;
+export default relationMatcherRoot;

package/dist/src/index.js

@@ -1,7 +1,7 @@
 import invertInput, {} from "./utils/invertInput";
 import { getJoinFinalKey } from "./utils/keys";
 import { matcherFunc } from "./utils/matcher";
-export const relationMatcher = (inputs, output) => {
+export const relationMatcherRoot = (inputs, output) => {
     if (!inputs.length)
         return {};
     if (!Array.isArray(inputs)) {
@@ -44,9 +44,8 @@ export const relationMatcher = (inputs, output) => {
     }, {});
     return baseItems;
 };
-/** @deprecated Use `relationMatcher`. */
-export const relationMatcherRoot = relationMatcher;
-export default relationMatcher;
+export const relationMatcher = relationMatcherRoot;
+export default relationMatcherRoot;
 const relationMatcherJoiner = (input, output, joiningFrom) => {
     return Object.entries(output).reduce((final, [key, value]) => {
         if (typeof value === "object") {

package/dist/src/testing/test-data.d.ts

@@ -1,4 +1,3 @@
-import type { RelationMapRoot } from "~/types/inputs";
 export declare const testData: ({
     users: {
         id: string;
@@ -69,4 +68,35 @@ export declare const testData: ({
     posts: null;
     comments: null;
 })[];
-export declare const testSchema: RelationMapRoot<(typeof testData)[number]>;
+export declare const testSchema: {
+    base: "users";
+    id: "id";
+    _teamToUsers: {
+        base: "teamToUser";
+        id: "teamId";
+        joinsFrom: "id";
+        joinsTo: "userId";
+        joinType: "array";
+        _team: {
+            base: "teams";
+            id: "id";
+            joinsFrom: "teamId";
+            joinsTo: "id";
+            joinType: "single";
+        };
+    };
+    _posts: {
+        base: "posts";
+        id: "id";
+        joinsFrom: "id";
+        joinsTo: "userId";
+        joinType: "array";
+        _comments: {
+            base: "comments";
+            id: "id";
+            joinsFrom: "id";
+            joinsTo: "postId";
+            joinType: "array";
+        };
+    };
+};

package/dist/src/types/return.d.ts

@@ -1,11 +1,9 @@
 import type { TInputBase, TJoinedFromBase, TOutputBase } from "./generic-bases";
 import type { RelationMapRoot } from "./inputs";
 import type { ExtendsNull, NoUnderscore, Simplify } from "./utils";
-export type RelationMapperReturnRoot<TInput extends TInputBase, TOutput extends RelationMapRoot<TInput>> = Simplify<{
-    [inputKey in keyof TInput]: ExtendsNull<TInput[TOutput["base"]]> extends true ? Simplify<TInput[TOutput["base"]] & RelationMapperReturnJoinRoot<TInput, TOutput, inputKey>> | null : Simplify<TInput[TOutput["base"]] & RelationMapperReturnJoinRoot<TInput, TOutput, inputKey>>;
-}[keyof TInput]>;
+export type RelationMapperReturnRoot<TInput extends TInputBase, TOutput extends RelationMapRoot<TInput>> = Simplify<ExtendsNull<TInput[TOutput["base"]]> extends true ? (TInput[TOutput["base"]] & RelationMapperReturnJoinRoot<TInput, TOutput, TOutput["base"]>) | null : TInput[TOutput["base"]] & RelationMapperReturnJoinRoot<TInput, TOutput, TOutput["base"]>>;
 export type RelationMapperReturnJoinRoot<TInput extends TInputBase, TOutput extends RelationMapRoot<TInput>, TInputKey extends keyof TInput> = {
-    [outputKey in NoUnderscore<keyof TOutput>]: Simplify<RelationMapperReturn<TInput, TInput[TInputKey], TOutput[`_${outputKey}`]>>;
+    [outputKey in NoUnderscore<keyof TOutput>]: RelationMapperReturn<TInput, TInput[TInputKey], TOutput[`_${outputKey}`]>;
 };
 /** Fill current object with value specified in base */
 export type RelationMapperReturn<TInput extends TInputBase, TJoinedFrom extends TJoinedFromBase, TOutput extends TOutputBase<TInput, TJoinedFrom>> = TOutput["joinType"] extends "array" ? Array<Simplify<TInput[TOutput["base"]] & RelationMapperReturnJoin<TInput, TJoinedFrom, TOutput>>> : ExtendsNull<TInput[TOutput["base"]]> extends true ? Simplify<TInput[TOutput["base"]] & RelationMapperReturnJoin<TInput, TJoinedFrom, TOutput>> | null : Simplify<TInput[TOutput["base"]] & RelationMapperReturnJoin<TInput, TJoinedFrom, TOutput>>;