relation-matcher 1.0.13 → 1.1.1

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

@@ -1,150 +1,185 @@
-# 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`.
+# 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.1
+
+- Major refactor.
+
+### 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.d.ts

@@ -1,6 +1,11 @@
-import type { TInputBase } from "./types/generic-bases";
-import type { RelationMapRoot } from "./types/inputs";
-import type { RelationMapperReturnRoot } from "./types/return";
-export declare const relationMatcherRoot: <TInput extends TInputBase, TOutputRoot extends RelationMapRoot<TInput>>(inputs: TInput[], output: TOutputRoot) => Record<string, RelationMapperReturnRoot<TInput, TOutputRoot>>;
-export declare const relationMatcher: <TInput extends TInputBase, TOutputRoot extends RelationMapRoot<TInput>>(inputs: TInput[], output: TOutputRoot) => Record<string, RelationMapperReturnRoot<TInput, TOutputRoot>>;
+import type { MaybeArray, MaybeNull, SRecord } from "./types";
+import type { TInputBase, TInputBaseJoin } from "./types/generic-bases";
+import type { Output, OutputRoot } from "./types/generic-less";
+import type { RelationMapRoot as Root } from "./types/inputs";
+import type { RelationMapperReturnRoot as ReturnRoot } from "./types/return";
+import { type InvertedInput } from "./utils/invertInput";
+export declare const relationMatcherRoot: <TInput extends TInputBase, TOutputRoot extends Root<TInput>>(inputs: TInput[], output: TOutputRoot) => SRecord<ReturnRoot<TInput, TOutputRoot>>;
+export declare const relationMatcher: <TInput extends TInputBase, TOutputRoot extends Root<TInput>>(inputs: TInput[], output: TOutputRoot) => SRecord<ReturnRoot<TInput, TOutputRoot>>;
 export default relationMatcherRoot;
+declare const joiner: (input: InvertedInput, output: Output | OutputRoot, joiningFrom: SRecord<unknown>) => SRecord<MaybeArray<MaybeNull<TInputBaseJoin>>>;
+export { joiner as relationMatcherJoiner };

package/dist/src/index.js

@@ -1,6 +1,8 @@
 import invertInput, {} from "./utils/invertInput";
+import { assertIsNullable } from "./utils/isNullable";
+import { arrayJoinBase, singleJoinBase } from "./utils/joins";
 import { getJoinFinalKey } from "./utils/keys";
-import { matcherFunc } from "./utils/matcher";
+import { createMatcherFunc } from "./utils/matcher";
 export const relationMatcherRoot = (inputs, output) => {
     if (!inputs.length)
         return {};
@@ -8,74 +10,61 @@ export const relationMatcherRoot = (inputs, output) => {
         throw new Error("Input must be an array.");
     }
     const invertedInput = invertInput(inputs);
-    const baseItems = invertedInput[output.base].reduce((final, row) => {
-        if (!row) {
+    const baseItems = invertedInput[output.base].reduce((final, inputRow) => {
+        if (!inputRow) {
             return final;
         }
-        const relations = Object.entries(output).reduce((final, [key, value]) => {
-            if (typeof value === "object") {
-                const finalKey = getJoinFinalKey(key);
-                if (value.joinType === "array") {
-                    const baseObjArr = invertedInput[value.base].filter(matcherFunc(row, value));
-                    final[finalKey] = Object.values(baseObjArr.reduce((final, item) => {
-                        if (!item)
-                            return final;
-                        final[item[value.id]] = {
-                            ...item,
-                            ...relationMatcherJoiner(invertedInput, value, item),
-                        };
-                        return final;
-                    }, {}));
-                }
-                else {
-                    const item = invertedInput[value.base].find(matcherFunc(row, value)) ?? null;
-                    if (item) {
-                        final[finalKey] = {
-                            ...item,
-                            ...relationMatcherJoiner(invertedInput, value, item),
-                        };
-                    }
-                }
-            }
-            return final;
-        }, {});
-        final[row[output.id]] = { ...row, ...relations };
+        const relations = joiner(invertedInput, output, inputRow);
+        const rowId = inputRow[output.id];
+        final[rowId] = {
+            ...inputRow,
+            ...relations,
+        };
         return final;
     }, {});
     return baseItems;
 };
 export const relationMatcher = relationMatcherRoot;
 export default relationMatcherRoot;
-const relationMatcherJoiner = (input, output, joiningFrom) => {
+const joiner = (input, output, joiningFrom) => {
     return Object.entries(output).reduce((final, [key, value]) => {
-        if (typeof value === "object") {
-            const finalKey = key.replace(/^_/, "");
-            const matcherFunc = (item) => item?.[value.joinsTo] === joiningFrom[value.joinsFrom];
-            if (value.joinType === "array") {
-                const baseObjArr = input[value.base].filter(matcherFunc);
+        if (typeof value !== "object")
+            return final;
+        const finalKey = getJoinFinalKey(key);
+        const matcherFunc = createMatcherFunc(joiningFrom, value);
+        const joinType = input[value.base];
+        if (!joinType)
+            throw new Error(`Input is missing rows for ${value.base}.`);
+        switch (value.joinType) {
+            case "array": {
+                const baseObjArr = arrayJoinBase(joinType, matcherFunc);
                 final[finalKey] = Object.values(baseObjArr.reduce((final, item) => {
-                    if (!item)
-                        return final;
                     const propertyKey = item[value.id];
-                    if (final[propertyKey])
-                        return final;
-                    final[propertyKey] = {
+                    final[propertyKey] ??= {
                         ...item,
-                        ...relationMatcherJoiner(input, value, item),
+                        ...joiner(input, value, item),
                     };
                     return final;
                 }, {}));
+                break;
             }
-            else {
-                const item = input[value.base].find(matcherFunc) ?? null;
+            case "single": {
+                const item = singleJoinBase(joinType, matcherFunc);
+                assertIsNullable(item, value.isNullable);
                 if (item) {
                     final[finalKey] = {
                         ...item,
-                        ...relationMatcherJoiner(input, value, item),
+                        ...joiner(input, value, item),
                     };
                 }
+                break;
+            }
+            default: {
+                value.joinType;
+                throw new Error(`Unhandled join type. Relation matcher can not handle ${value.joinType}.`);
             }
         }
         return final;
     }, {});
 };
+export { joiner as relationMatcherJoiner };

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

@@ -1,4 +1,5 @@
 import type { RelationMapBase, RelationMapJoiner } from "./inputs";
-export type TInputBase = Record<string, Record<string, unknown> | null>;
+export type TInputBaseJoin = Record<string, unknown>;
+export type TInputBase = Record<string, TInputBaseJoin | null>;
 export type TJoinedFromBase = TInputBase[keyof TInputBase];
 export type TOutputBase<TInput extends TInputBase, TJoinedFrom extends TJoinedFromBase> = RelationMapBase<TInput, TJoinedFrom> & RelationMapJoiner<TInput, TJoinedFrom>;

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

@@ -1,11 +1,16 @@
-import type { TInputBase } from "./generic-bases";
-export type Output<TJoinType extends "single" | "array" = "single" | "array"> = OutputJoins & {
-    base: keyof TInputBase;
+export type OutputBase<TJoinType extends "single" | "array" = "single" | "array"> = {
+    base: string;
     id: string;
     joinsTo: string;
     joinsFrom: string;
     joinType: TJoinType;
+    isNullable?: false;
 };
+export type OutputRoot = OutputJoins & {
+    base: string;
+    id: string;
+};
+export type Output<TJoinType extends "single" | "array" = "single" | "array"> = OutputJoins & OutputBase<TJoinType>;
 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/types/utils.d.ts

@@ -11,3 +11,6 @@ export type DeepNonNullable<T extends object> = {
 export type ArrayOrSingle<T, TType extends "single" | "array"> = TType extends "array" ? Array<T> : T;
 export type IsNullIfNull<TIsNull extends object | null, TReturn extends object | never = never> = TIsNull extends infer T ? (T & TReturn) | null : TIsNull & TReturn;
 export type ExtendsNull<T> = null extends T ? true : false;
+export type MaybeNull<T> = T | null;
+export type MaybeArray<T> = T | T[];
+export type SRecord<T> = Record<string, T>;

package/dist/src/utils/invertInput.d.ts

@@ -1,4 +1,5 @@
 import type { TInputBase } from "~/types/generic-bases";
-export type InvertedInput<TInput extends TInputBase = TInputBase> = Record<keyof TInput, TInput[keyof TInput][]>;
+export type InvertedInputRow<TInput extends TInputBase = TInputBase> = TInput[keyof TInput][];
+export type InvertedInput<TInput extends TInputBase = TInputBase> = Record<keyof TInput, InvertedInputRow<TInput>>;
 declare const invertInput: <TInput extends TInputBase>(inputs: TInputBase[]) => InvertedInput<TInput>;
 export default invertInput;

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/isNullable.d.ts

@@ -0,0 +1,2 @@
+/** Asserts that if `isNullable` is false then item is not null. */
+export declare const assertIsNullable: (item: Record<string, unknown> | null, isNullable: false | undefined) => void;

package/dist/src/utils/isNullable.js

@@ -0,0 +1,6 @@
+/** Asserts that if `isNullable` is false then item is not null. */
+export const assertIsNullable = (item, isNullable) => {
+    if (isNullable === false && item === null) {
+        throw new Error("Value should exist as output schema defines it as nullable. Instead found null in array");
+    }
+};

package/dist/src/utils/joins.d.ts

@@ -0,0 +1,5 @@
+import type { OutputBase } from "~/types";
+import type { InvertedInputRow } from "./invertInput";
+import { type MatcherFunc } from "./matcher";
+export declare const singleJoinBase: <TValue extends OutputBase<"single">>(input: InvertedInputRow, matcherFunc: MatcherFunc) => Record<string, unknown> | null;
+export declare const arrayJoinBase: <TValue extends OutputBase<"single">>(input: InvertedInputRow, matcherFunc: MatcherFunc) => Record<string, unknown>[];

package/dist/src/utils/joins.js

@@ -0,0 +1,9 @@
+import {} from "./matcher";
+export const singleJoinBase = (input, matcherFunc) => {
+    const item = input.find(matcherFunc) ?? null;
+    return item;
+};
+export const arrayJoinBase = (input, matcherFunc) => {
+    const item = input.filter(matcherFunc);
+    return item;
+};

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);
+};