Add references to link schemas to each other

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @123ishatest/louter
 
+## 0.5.0
+
+### Minor Changes
+
+- 18d405b: Add references to link schemas to each other
+
 ## 0.4.0
 
 ### Minor Changes

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@123ishatest/louter",
   "private": false,
-  "version": "0.4.0",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -54,6 +54,7 @@
     "vitest": "^4.0.6"
   },
   "dependencies": {
+    "es-toolkit": "^1.46.1",
     "yaml": "^2.8.2",
     "zod": "^4.3.6"
   }

src/core/LouterWarningType.ts

@@ -4,6 +4,8 @@ export enum LouterWarningType {
   InvalidYaml = 'InvalidYaml',
   InvalidJson = 'InvalidJson',
   MissingGlobalIdKey = 'MissingGlobalIdKey',
+  MissingReference = 'MissingReference',
+  MissingReferenceKind = 'MissingReferenceKind',
   ZodParsingFailed = 'ZodParsingFailed',
   DuplicateId = 'DuplicateId',
 }

src/core/references.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+
+export const LOUTER_REFERENCE_PREFIX = '$ref';
+export const LOUTER_SEPARATOR = ':';
+
+export function ref(kind: string) {
+  return z.string().transform((v) => `${LOUTER_REFERENCE_PREFIX}${LOUTER_SEPARATOR}${kind}${LOUTER_SEPARATOR}${v}`);
+}

src/validator/LouterValidator.ts

@@ -3,12 +3,19 @@ import type { KindDefinitions } from '@louter/core/types';
 import type { LouterStage } from '@louter/core/LouterStage';
 import type { LouterContext } from '@louter/core/LouterContext';
 import { LouterWarningType } from '@louter/core/LouterWarningType';
+import { flattenObject } from 'es-toolkit';
+import { LOUTER_REFERENCE_PREFIX, LOUTER_SEPARATOR } from '@louter/core/references';
 
 /**
  * Validate all LouterObjects through their Zod schemas
  */
 export class LouterValidator implements LouterStage {
   run<Kinds extends KindDefinitions>(ctx: LouterContext<Kinds>): void {
+    this.parse(ctx);
+    this.validateReferences(ctx);
+  }
+
+  parse<Kinds extends KindDefinitions>(ctx: LouterContext<Kinds>): void {
     ctx.objects.forEach((object) => {
       const schema = ctx.kinds[object.kind];
       if (!schema) {
@@ -53,4 +60,38 @@ export class LouterValidator implements LouterStage {
       ctx.content[object.kind][id] = zodResult.data;
     });
   }
+
+  validateReferences<Kinds extends KindDefinitions>(ctx: LouterContext<Kinds>): void {
+    Object.values(ctx.content).forEach((items) => {
+      Object.values(items).forEach((item) => {
+        const flat = flattenObject(item as object);
+
+        Object.entries(flat).forEach(([key, value]) => {
+          if (value.toString().startsWith(LOUTER_REFERENCE_PREFIX)) {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const [_, kind, ...rest] = value.split(LOUTER_SEPARATOR);
+            const refId = rest.join(LOUTER_SEPARATOR);
+
+            if (!ctx.content[kind]) {
+              ctx.warnings.push({
+                type: LouterWarningType.MissingReferenceKind,
+                message: `Missing reference kind '${kind}'`,
+                path: key,
+              });
+              return;
+            }
+
+            if (!ctx.content[kind][refId]) {
+              ctx.warnings.push({
+                type: LouterWarningType.MissingReference,
+                message: `Missing reference '${value}'`,
+                path: key,
+              });
+              return;
+            }
+          }
+        });
+      });
+    });
+  }
 }

tests/validator/louter-reference-validator.spec.ts

@@ -0,0 +1,122 @@
+import { expect, it } from 'vitest';
+import z from 'zod';
+import { createContext } from '@louter/core/util';
+import { LouterValidator } from '@louter/validator/LouterValidator';
+import { LouterWarningType } from '@louter/core/LouterWarningType';
+import { ref } from '@louter/core/references';
+
+it('resolves references', () => {
+  // Arrange
+  const parser = new LouterValidator();
+  const ctx = createContext({
+    first: z.strictObject({
+      id: z.string(),
+    }),
+    second: z.strictObject({
+      id: z.string(),
+      first: ref('first'),
+    }),
+  });
+  const firstPiece = { id: 'a' };
+  const secondPiece = { id: 'b', first: 'a' };
+  ctx.content.first = {
+    a: firstPiece,
+  };
+  ctx.content.second = {
+    b: secondPiece,
+  };
+
+  // Act
+  parser.run(ctx);
+
+  // Assert
+  expect(ctx.warnings).toStrictEqual([]);
+  expect(ctx.content.first.a).toStrictEqual(firstPiece);
+  expect(ctx.content.second.b).toStrictEqual(secondPiece);
+});
+
+it('fails on incorrect kinds', () => {
+  // Arrange
+  const validator = new LouterValidator();
+  const ctx = createContext({
+    example: z.strictObject({
+      id: z.string(),
+      relation: ref('wrong'),
+    }),
+  });
+  ctx.objects = [{ path: 'a.example.json', kind: 'example', data: { id: 'a', relation: 'wrong-id' } }];
+
+  // Act
+  validator.run(ctx);
+
+  // Assert
+  expect(ctx.warnings).toHaveLength(1);
+  expect(ctx.warnings[0].type).toBe(LouterWarningType.MissingReferenceKind);
+});
+
+it('fails on incorrect references', () => {
+  // Arrange
+  const validator = new LouterValidator();
+  const ctx = createContext({
+    first: z.strictObject({
+      id: z.string(),
+    }),
+    second: z.strictObject({
+      id: z.string(),
+      first: ref('first'),
+    }),
+  });
+  ctx.objects = [
+    { path: 'a.first.json', kind: 'first', data: { id: 'a' } },
+    { path: 'b.second.json', kind: 'second', data: { id: 'b', first: 'wrong' } },
+  ];
+
+  // Act
+  validator.run(ctx);
+
+  // Assert
+  expect(ctx.warnings).toHaveLength(1);
+  expect(ctx.warnings[0].type).toBe(LouterWarningType.MissingReference);
+});
+
+it("doesn't break when using special characters", () => {
+  // Arrange
+  const validator = new LouterValidator();
+  const ctx = createContext({
+    first: z.strictObject({
+      id: z.string(),
+    }),
+    second: z.strictObject({
+      id: z.string(),
+      first: ref('first'),
+    }),
+  });
+  ctx.objects = [
+    { path: 'a.first.json', kind: 'first', data: { id: 'a:detail' } },
+    { path: 'b.second.json', kind: 'second', data: { id: 'b', first: 'a:detail' } },
+  ];
+
+  // Act
+  validator.run(ctx);
+
+  // Assert
+  expect(ctx.warnings).toHaveLength(0);
+});
+
+it('can reference itself', () => {
+  // Arrange
+  const validator = new LouterValidator();
+  const ctx = createContext({
+    item: z.strictObject({
+      id: z.string(),
+      meta: ref('item'),
+    }),
+  });
+  ctx.objects = [{ path: 'a.item.json', kind: 'item', data: { id: 'a', meta: 'a' } }];
+
+  // Act
+  validator.run(ctx);
+
+  // Assert
+  expect(ctx.warnings).toStrictEqual([]);
+});