relation-matcher 1.0.12 → 1.1.0

package/.yarnrc.yml

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

package/README.md

@@ -0,0 +1,181 @@
+# 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)
+- [Changelog](#changelog)
+
+## 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 db from "~/db/client";
+// ...otherImports
+import relationMatcher from "relation-matcher";
+
+/* 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
+		post_category_id: string; // < Same as post_category.id
+	};
+
+	post_category: {
+		id: string;
+		name: string;
+	} | null;
+}[]
+```
+
+### `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",
+		isNullable?: false | undefined, // No-op on array join types.
+	},
+}
+```
+
+> [!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",
+
+		_postCategory: {
+			base: "post_category",
+			id: "id",
+			joinsFrom: "post_category_id",
+			joinsTo: "id",
+			joinType: "single",
+			isNullable: false,
+		},
+	},
+}
+```
+
+### `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;
+				post_category_id: string;
+
+				postCategory: {
+					id: string;
+					name: string;
+				} // | null;
+				  // Note this is not nullable as the schema defined it as such.
+			}
+		>;
+	}
+>;
+```
+
+## Changelog
+
+### 1.1.0
+
+- Added ability to mark join as `isNullable: false`. This allows for manual marking of single joins as `NonNullable`.
+
+    Will throw `Error` if value is not found.
+
+### 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.js

@@ -49,8 +49,10 @@ export default relationMatcherRoot;
 const relationMatcherJoiner = (input, output, joiningFrom) => {
     return Object.entries(output).reduce((final, [key, value]) => {
         if (typeof value === "object") {
-            const finalKey = key.replace(/^_/, "");
+            const finalKey = getJoinFinalKey(key);
             const matcherFunc = (item) => item?.[value.joinsTo] === joiningFrom[value.joinsFrom];
+            if (!input[value.base])
+                throw new Error(`Input is missing rows for ${value.base}.`);
             if (value.joinType === "array") {
                 const baseObjArr = input[value.base].filter(matcherFunc);
                 final[finalKey] = Object.values(baseObjArr.reduce((final, item) => {
@@ -68,6 +70,9 @@ const relationMatcherJoiner = (input, output, joiningFrom) => {
             }
             else {
                 const item = input[value.base].find(matcherFunc) ?? null;
+                if (item === null && value.isNullable === false) {
+                    throw new Error("Value should exist as output schema defines it as nullable. Instead found null in array");
+                }
                 if (item) {
                     final[finalKey] = {
                         ...item,

package/dist/src/types/generic-less.d.ts

@@ -5,6 +5,7 @@ export type Output<TJoinType extends "single" | "array" = "single" | "array"> =
     joinsTo: string;
     joinsFrom: string;
     joinType: TJoinType;
+    isNullable?: false;
 };
 export type OutputJoins = {
     [k: `_${string}`]: Output;

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

@@ -5,15 +5,22 @@ export type RelationMapRoot<TInput extends TInputBase> = {
         id: keyof NonNullable<TInput[k]>;
     } & RelationMapJoiner<TInput, NonNullable<TInput[k]>>;
 }[keyof TInput];
+export type IsNullable = {
+    false: false;
+    undefined: undefined;
+};
 export type RelationMapBase<TInput extends TInputBase, TJoinedFrom extends TJoinedFromBase> = {
     [k in keyof TInput]: {
-        base: k;
-        /** The id that uniqueness is checked against. Either the primary key of the table, or the id you are joining **to** on a join table. */
-        id: keyof NonNullable<TInput[k]>;
-        joinsTo: keyof NonNullable<TInput[k]>;
-        joinsFrom: keyof NonNullable<TJoinedFrom>;
-        joinType: "single" | "array";
-    } & RelationMapJoiner<TInput, TInput[k]>;
+        [n in keyof IsNullable]: {
+            base: k;
+            /** The id that uniqueness is checked against. Either the primary key of the table, or the id you are joining **to** on a join table. */
+            id: keyof NonNullable<TInput[k]>;
+            joinsTo: keyof NonNullable<TInput[k]>;
+            joinsFrom: keyof NonNullable<TJoinedFrom>;
+            joinType: "single" | "array";
+            isNullable?: IsNullable[n];
+        };
+    }[keyof IsNullable] & RelationMapJoiner<TInput, TInput[k]>;
 }[keyof TInput];
 export type RelationMapJoiner<TInput extends TInputBase, TJoinedFrom extends TJoinedFromBase> = {
     [k: `_${string}`]: RelationMapBase<TInput, TJoinedFrom> & RelationMapJoiner<TInput, TJoinedFrom>;

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

@@ -1,13 +1,16 @@
 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<ExtendsNull<TInput[TOutput["base"]]> extends true ? (TInput[TOutput["base"]] & RelationMapperReturnJoinRoot<TInput, TOutput, TOutput["base"]>) | null : TInput[TOutput["base"]] & RelationMapperReturnJoinRoot<TInput, TOutput, TOutput["base"]>>;
+type JoinedRoot<TInput extends TInputBase, TOutput extends RelationMapRoot<TInput>> = TInput[TOutput["base"]] & RelationMapperReturnJoinRoot<TInput, TOutput, TOutput["base"]>;
+export type RelationMapperReturnRoot<TInput extends TInputBase, TOutput extends RelationMapRoot<TInput>> = Simplify<ExtendsNull<TInput[TOutput["base"]]> extends true ? JoinedRoot<TInput, TOutput> | null : JoinedRoot<TInput, TOutput>>;
 export type RelationMapperReturnJoinRoot<TInput extends TInputBase, TOutput extends RelationMapRoot<TInput>, TInputKey extends keyof TInput> = {
     [outputKey in NoUnderscore<keyof TOutput>]: RelationMapperReturn<TInput, TInput[TInputKey], TOutput[`_${outputKey}`]>;
 };
+export type Joined<TInput extends TInputBase, TJoinedFrom extends TJoinedFromBase, TOutput extends TOutputBase<TInput, TJoinedFrom>> = Simplify<TInput[TOutput["base"]] & RelationMapperReturnJoin<TInput, TJoinedFrom, TOutput>>;
 /** 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>>;
+export type RelationMapperReturn<TInput extends TInputBase, TJoinedFrom extends TJoinedFromBase, TOutput extends TOutputBase<TInput, TJoinedFrom>> = TOutput["joinType"] extends "array" ? Array<Joined<TInput, TJoinedFrom, TOutput>> : ExtendsNull<TInput[TOutput["base"]]> extends true ? TOutput["isNullable"] extends false ? Joined<TInput, TJoinedFrom, TOutput> : Joined<TInput, TJoinedFrom, TOutput> | null : Joined<TInput, TJoinedFrom, TOutput>;
 /** Takes underscored values (joins) and replaces their values with the actual output. */
 export type RelationMapperReturnJoin<TInput extends TInputBase, TJoinedFrom extends TJoinedFromBase, TOutput extends TOutputBase<TInput, TJoinedFrom>> = {
     [k in NoUnderscore<keyof TOutput>]: RelationMapperReturn<TInput, TJoinedFrom, TOutput[`_${k}`]>;
 };
+export {};

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

@@ -24,6 +24,7 @@ export type A = DeepSimplify<RelationMapperReturnRoot<{
         joinsTo: "team_id";
         joinsFrom: "id";
         joinType: "single";
+        isNullable: false;
         _team: {
             base: "team";
             id: "id";

package/dist/src/utils/invertInput.js

@@ -1,15 +1,10 @@
 const invertInput = (inputs) => {
     const invertedInput = inputs.reduce((final, row) => {
         Object.entries(row).forEach(([header, value]) => {
-            if (final[header]) {
-                if (value)
-                    final[header].push(value);
-            }
-            else {
-                final[header] = value
-                    ? [value]
-                    : [];
-            }
+            final[header] ??= [];
+            // Instantiated above.
+            if (value)
+                final[header].push(value);
         });
         return final;
     }, {});

package/dist/src/utils/keys.js

@@ -1 +1,6 @@
-export const getJoinFinalKey = (key) => key.substring(1);
+export const getJoinFinalKey = (key) => {
+    if (key[0] !== "_") {
+        throw new Error("Joining key must start with underscore.");
+    }
+    return key.substring(1);
+};