@cronn/lib-file-snapshots 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,15 +1,125 @@
-interface SerializerResult {
-    value: string;
+interface SnapshotSerializer {
+    /**
+     * Returns true when value can be serialized
+     *
+     * @param value The value to be serialized
+     */
+    canSerialize(value: unknown): boolean;
+    /**
+     * Serializes value
+     *
+     * @param value The value to be serialized
+     * @throws {Error} Will throw an error if value cannot be serialized.
+     */
+    serialize(value: unknown): SnapshotSerializerResult;
+}
+interface SnapshotSerializerResult {
+    /**
+     * The serialized value
+     */
+    serializedValue: string;
+    /**
+     * The file extension associated with the serialized value
+     */
     fileExtension: string;
 }
 
+declare class CompositeSerializer implements SnapshotSerializer {
+    private readonly serializers;
+    constructor(serializers: SnapshotSerializer[]);
+    canSerialize(value: unknown): boolean;
+    serialize(value: unknown): SnapshotSerializerResult;
+}
+
 interface JsonSerializerOptions {
-    includeUndefinedObjectProperties: boolean;
+    /**
+     * Serializes `undefined` properties in objects. By default, they are omitted.
+     *
+     * @default false
+     */
+    includeUndefinedObjectProperties?: boolean;
+}
+declare class JsonSerializer implements SnapshotSerializer {
+    private readonly includeUndefinedObjectProperties;
+    constructor(options?: JsonSerializerOptions);
+    canSerialize(value: unknown): boolean;
+    serialize(value: unknown): SnapshotSerializerResult;
+    private normalizeValueRecursive;
+    private normalizeValue;
+    private normalizeNumber;
+    private normalizeArray;
+    private normalizeObject;
+    private normalizeDate;
+    private normalizePlainObject;
+    private normalizeMap;
+    private serializedValue;
+    private assertKeyType;
+}
+
+declare class TextSerializer implements SnapshotSerializer {
+    canSerialize(value: unknown): value is string;
+    serialize(value: unknown): SnapshotSerializerResult;
+    private normalizeValue;
 }
-declare function serializeAsJson(value: unknown, options: JsonSerializerOptions): SerializerResult;
 
-declare function serializeAsText(value: unknown): SerializerResult;
+interface ValidationFileMatcherConfig {
+    /**
+     * Base directory for tests
+     *
+     * The paths of snapshot files will be relative to this directory.
+     * @default "."
+     */
+    baseDir?: string;
+    /**
+     * Directory in which golden masters are stored
+     *
+     * @default "data/test/validation"
+     */
+    validationDir?: string;
+    /**
+     * Directory in which file snapshots from test runs are stored
+     *
+     * @default "data/test/output"
+     */
+    outputDir?: string;
+}
+interface MatchValidationFileOptions {
+    /**
+     * The full name of the test, including the names of nested describe blocks
+     *
+     * @example ["test feature", "when x, then y"]
+     */
+    testName: string[];
+    /**
+     * The directory in which the current test is located
+     */
+    testDir: string;
+    /**
+     * Appends `fileSuffix` to the generated snapshot file
+     *
+     * Should be used whenever having multiple snapshot assertions in a single `test`.
+     */
+    fileSuffix?: string;
+    /**
+     * The serializer to use for the snapshot
+     */
+    serializer: SnapshotSerializer;
+}
+interface ValidationFileMatcherResult {
+    actual: string;
+    expected: string;
+    actualFile: string;
+    validationFile: string;
+}
 
-declare function normalizeTestName(testName: string): string;
+declare class ValidationFileMatcher {
+    private readonly baseDir;
+    private readonly validationDir;
+    private readonly outputDir;
+    constructor(config?: ValidationFileMatcherConfig);
+    matchFileSnapshot(actual: unknown, options: MatchValidationFileOptions): ValidationFileMatcherResult;
+    private buildValidationFilePath;
+    private writeFileSnapshots;
+}
 
-export { type SerializerResult, normalizeTestName, serializeAsJson, serializeAsText };
+export { CompositeSerializer, JsonSerializer, TextSerializer, ValidationFileMatcher };

package/dist/index.js

@@ -1,4 +1,25 @@
-// src/guards.ts
+// src/serializers/composite-serializer.ts
+var CompositeSerializer = class {
+  serializers;
+  constructor(serializers) {
+    this.serializers = serializers;
+  }
+  canSerialize(value) {
+    return this.serializers.some(
+      (serializer) => serializer.canSerialize(value)
+    );
+  }
+  serialize(value) {
+    for (const serializer of this.serializers) {
+      if (serializer.canSerialize(value)) {
+        return serializer.serialize(value);
+      }
+    }
+    throw new Error(`Missing serializer for value of type ${typeof value}.`);
+  }
+};
+
+// src/utils/guards.ts
 function isArray(value) {
   return Array.isArray(value);
 }
@@ -13,157 +34,270 @@ function isPlainObject(value) {
   return proto === null || proto === Object.prototype;
 }
 
-// src/json-serializer.ts
-function serializeAsJson(value, options) {
-  const jsonValue = isPlainObject(value) || isArray(value) ? normalizeValueRecursive(value, options) : normalizeValue(value, options);
-  const serializedValue = JSON.stringify(jsonValue, void 0, 2);
-  return {
-    value: serializedValue,
-    fileExtension: "json"
-  };
-}
-function normalizeValueRecursive(value, options) {
-  if (isArray(value)) {
-    return normalizeArray(value, options);
+// src/serializers/json-serializer.ts
+var JsonSerializer = class {
+  includeUndefinedObjectProperties;
+  constructor(options = {}) {
+    this.includeUndefinedObjectProperties = options.includeUndefinedObjectProperties ?? false;
   }
-  if (isPlainObject(value)) {
-    return normalizePlainObject(value, options);
+  canSerialize(value) {
+    return true;
   }
-  if (typeof value === "string" || typeof value === "boolean" || value === null) {
-    return value;
+  serialize(value) {
+    const jsonValue = isPlainObject(value) || isArray(value) ? this.normalizeValueRecursive(value) : this.normalizeValue(value);
+    const serializedValue = JSON.stringify(jsonValue, void 0, 2);
+    return {
+      serializedValue,
+      fileExtension: "json"
+    };
   }
-  return normalizeValue(value, options);
-}
-function normalizeValue(value, options) {
-  if (value === void 0) {
-    return normalizedValue("undefined");
-  }
-  if (value === null || typeof value === "string" || typeof value === "boolean") {
-    return normalizedValue(typeof value, { value });
-  }
-  if (typeof value === "number") {
-    return normalizeNumber(value);
+  normalizeValueRecursive(value) {
+    if (isArray(value)) {
+      return this.normalizeArray(value);
+    }
+    if (isPlainObject(value)) {
+      return this.normalizePlainObject(value);
+    }
+    if (typeof value === "string" || typeof value === "boolean" || value === null) {
+      return value;
+    }
+    return this.normalizeValue(value);
   }
-  if (typeof value === "bigint") {
-    return normalizedValue("bigint", { value: value.toString() });
+  normalizeValue(value) {
+    if (value === void 0) {
+      return this.serializedValue("undefined");
+    }
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+      return this.serializedValue(typeof value, { value });
+    }
+    if (typeof value === "number") {
+      return this.normalizeNumber(value);
+    }
+    if (typeof value === "bigint") {
+      return this.serializedValue("bigint", { value: value.toString() });
+    }
+    if (typeof value === "symbol") {
+      return this.serializedValue("symbol", { description: value.description });
+    }
+    if (typeof value === "function") {
+      return this.serializedValue("function", { name: value.name });
+    }
+    if (typeof value === "object") {
+      return this.normalizeObject(value);
+    }
+    throw new Error(
+      `Missing JSON normalization for value of type ${typeof value}.`
+    );
   }
-  if (typeof value === "symbol") {
-    return normalizedValue("symbol", { description: value.description });
+  normalizeNumber(value) {
+    if (Number.isNaN(value)) {
+      return this.serializedValue("number", { value: "Number.NaN" });
+    }
+    switch (value) {
+      case Number.MIN_VALUE:
+        return this.serializedValue("number", { value: "Number.MIN_VALUE" });
+      case Number.MAX_VALUE:
+        return this.serializedValue("number", { value: "Number.MAX_VALUE" });
+      case Number.MIN_SAFE_INTEGER:
+        return this.serializedValue("number", {
+          value: "Number.MIN_SAFE_INTEGER"
+        });
+      case Number.MAX_SAFE_INTEGER:
+        return this.serializedValue("number", {
+          value: "Number.MAX_SAFE_INTEGER"
+        });
+      case Number.NEGATIVE_INFINITY:
+        return this.serializedValue("number", {
+          value: "Number.NEGATIVE_INFINITY"
+        });
+      case Number.POSITIVE_INFINITY:
+        return this.serializedValue("number", {
+          value: "Number.POSITIVE_INFINITY"
+        });
+      default:
+        return value;
+    }
   }
-  if (typeof value === "function") {
-    return normalizedValue("function", { name: value.name });
+  normalizeArray(value) {
+    return value.map((item) => this.normalizeValueRecursive(item));
   }
-  if (typeof value === "object") {
-    return normalizeObject(value, options);
+  normalizeObject(value) {
+    if (value instanceof Date) {
+      return this.normalizeDate(value);
+    }
+    if (value instanceof Promise) {
+      return this.serializedValue("Promise");
+    }
+    if (value instanceof Set) {
+      return this.serializedValue("Set", {
+        values: this.normalizeArray(Array.from(value.values()))
+      });
+    }
+    if (value instanceof Map) {
+      const mapAsObject = this.normalizeMap(value);
+      return this.serializedValue("Map", {
+        values: this.normalizePlainObject(mapAsObject)
+      });
+    }
+    throw new Error(
+      `Missing JSON normalization for object of type ${Object.getPrototypeOf(value)}`
+    );
   }
-  throw new Error(
-    `Missing JSON normalization for value of type ${typeof value}.`
-  );
-}
-function normalizeNumber(value) {
-  if (Number.isNaN(value)) {
-    return normalizedValue("number", { value: "Number.NaN" });
-  }
-  switch (value) {
-    case Number.MIN_VALUE:
-      return normalizedValue("number", { value: "Number.MIN_VALUE" });
-    case Number.MAX_VALUE:
-      return normalizedValue("number", { value: "Number.MAX_VALUE" });
-    case Number.MIN_SAFE_INTEGER:
-      return normalizedValue("number", { value: "Number.MIN_SAFE_INTEGER" });
-    case Number.MAX_SAFE_INTEGER:
-      return normalizedValue("number", { value: "Number.MAX_SAFE_INTEGER" });
-    case Number.NEGATIVE_INFINITY:
-      return normalizedValue("number", { value: "Number.NEGATIVE_INFINITY" });
-    case Number.POSITIVE_INFINITY:
-      return normalizedValue("number", { value: "Number.POSITIVE_INFINITY" });
-    default:
-      return value;
+  normalizeDate(value) {
+    if (Number.isNaN(value.getTime())) {
+      return this.serializedValue("Date", { value: "Invalid date" });
+    }
+    return this.serializedValue("Date", { value: value.toISOString() });
   }
-}
-function normalizeArray(value, options) {
-  return value.map((item) => normalizeValueRecursive(item, options));
-}
-function normalizeObject(value, options) {
-  if (value instanceof Date) {
-    return normalizeDate(value);
+  normalizePlainObject(value) {
+    const normalizedObject = {};
+    for (const [key, propertyValue] of Object.entries(value)) {
+      if (propertyValue === void 0 && !this.includeUndefinedObjectProperties) {
+        continue;
+      }
+      this.assertKeyType(key);
+      normalizedObject[key] = this.normalizeValueRecursive(propertyValue);
+    }
+    return normalizedObject;
   }
-  if (value instanceof Promise) {
-    return normalizedValue("Promise");
+  normalizeMap(value) {
+    return Array.from(value.entries()).reduce(
+      (object, [key, value2]) => {
+        this.assertKeyType(key);
+        object[key] = value2;
+        return object;
+      },
+      {}
+    );
   }
-  if (value instanceof Set) {
-    return normalizedValue("Set", {
-      values: normalizeArray(Array.from(value.values()), options)
-    });
+  serializedValue(type, additionalProps = {}) {
+    return { $type: type, ...additionalProps };
   }
-  if (value instanceof Map) {
-    const mapAsObject = normalizeMap(value);
-    return normalizedValue("Map", {
-      values: normalizePlainObject(mapAsObject, options)
-    });
+  assertKeyType(key) {
+    if (!(typeof key === "string")) {
+      throw new Error(`Key of type ${typeof key} cannot be normalized.`);
+    }
   }
-  throw new Error(
-    `Missing JSON normalization for object of type ${Object.getPrototypeOf(value)}`
-  );
-}
-function normalizeDate(value) {
-  if (Number.isNaN(value.getTime())) {
-    return normalizedValue("Date", { value: "Invalid date" });
+};
+
+// src/serializers/text-serializer.ts
+var TextSerializer = class {
+  canSerialize(value) {
+    return typeof value === "string";
   }
-  return normalizedValue("Date", { value: value.toISOString() });
-}
-function normalizePlainObject(value, options) {
-  const normalizedObject = {};
-  for (const [key, propertyValue] of Object.entries(value)) {
-    if (propertyValue === void 0 && !options.includeUndefinedObjectProperties) {
-      continue;
+  serialize(value) {
+    if (!this.canSerialize(value)) {
+      throw new Error(
+        `Missing text serialization for value of type ${typeof value}.`
+      );
     }
-    assertKeyType(key);
-    normalizedObject[key] = normalizeValueRecursive(propertyValue, options);
+    return {
+      serializedValue: this.normalizeValue(value),
+      fileExtension: "txt"
+    };
+  }
+  normalizeValue(value) {
+    return value.trim();
   }
-  return normalizedObject;
+};
+
+// src/matcher/validation-file-matcher.ts
+import * as fs2 from "fs";
+import * as path from "path";
+import "vitest";
+
+// src/utils/file.ts
+import fs from "fs";
+var NEW_LINE_SEPARATOR = "\n";
+function normalizeFileName(testName) {
+  return testName.replaceAll(/\+0/g, "0").replaceAll(/'([\w ]+)'/g, "$1").replaceAll(/[ .:']/g, "_").replaceAll(/,/g, "");
 }
-function normalizeMap(value) {
-  return Array.from(value.entries()).reduce(
-    (object, [key, value2]) => {
-      assertKeyType(key);
-      object[key] = value2;
-      return object;
-    },
-    {}
-  );
+function mkdirRecursive(path2) {
+  fs.mkdirSync(path2, { recursive: true });
 }
-function normalizedValue(type, additionalProps = {}) {
-  return { $type: type, ...additionalProps };
+function readSnapshotFile(path2) {
+  return fs.readFileSync(path2, { encoding: "utf8" });
 }
-function assertKeyType(key) {
-  if (!(typeof key === "string")) {
-    throw new Error(`Key of type ${typeof key} cannot be normalized.`);
+function writeSnapshotFile(file, data, markAsMissing = false) {
+  let finalizedData = addTrailingNewLine(data);
+  if (markAsMissing) {
+    finalizedData = addMissingFileMarker(finalizedData);
   }
+  fs.writeFileSync(file, finalizedData, { encoding: "utf8" });
 }
-
-// src/text-serializer.ts
-function serializeAsText(value) {
-  return {
-    value: normalizeValue2(value),
-    fileExtension: "txt"
-  };
+function addTrailingNewLine(data) {
+  return `${data}${NEW_LINE_SEPARATOR}`;
 }
-function normalizeValue2(value) {
-  if (typeof value === "string") {
-    return value.trim();
-  }
-  throw new Error(
-    `Missing text normalization for value of type ${typeof value}.`
-  );
+function addMissingFileMarker(data) {
+  return `===== missing file =====${NEW_LINE_SEPARATOR}${data}`;
 }
 
-// src/normalizers.ts
-function normalizeTestName(testName) {
-  return testName.replaceAll(/\+0/g, "0").replaceAll(/'([\w ]+)'/g, "$1").replaceAll(/[ .:']/g, "_").replaceAll(/,/g, "");
-}
+// src/matcher/validation-file-matcher.ts
+var ValidationFileMatcher = class {
+  baseDir;
+  validationDir;
+  outputDir;
+  constructor(config = {}) {
+    this.baseDir = config.baseDir ?? ".";
+    this.validationDir = config.validationDir ?? "data/test/validation";
+    this.outputDir = config.outputDir ?? "data/test/output";
+  }
+  matchFileSnapshot(actual, options) {
+    const { testName, testDir, fileSuffix, serializer } = options;
+    if (!serializer.canSerialize(actual)) {
+      throw new Error(`Cannot serialize value of type ${typeof actual}`);
+    }
+    const serializerResult = serializer.serialize(actual);
+    const validationFilePath = this.buildValidationFilePath({
+      testName,
+      testDir,
+      fileSuffix,
+      fileExtension: serializerResult.fileExtension
+    });
+    return this.writeFileSnapshots(
+      serializerResult.serializedValue,
+      validationFilePath
+    );
+  }
+  buildValidationFilePath(options) {
+    const { testName, testDir, fileSuffix, fileExtension } = options;
+    const normalizedTestNames = testName.map(normalizeFileName);
+    const normalizedFileSuffix = fileSuffix !== void 0 ? `_${normalizeFileName(fileSuffix)}` : "";
+    const normalizedTestName = normalizedTestNames.pop();
+    const absoluteValidationFilePath = path.join(
+      testDir,
+      ...normalizedTestNames
+    );
+    const relativeValidationFilePath = path.relative(
+      this.baseDir,
+      absoluteValidationFilePath
+    );
+    const validationFileName = `${normalizedTestName}${normalizedFileSuffix}.${fileExtension}`;
+    return path.join(relativeValidationFilePath, validationFileName);
+  }
+  writeFileSnapshots(actual, validationFilePath) {
+    const validationFileDir = path.dirname(validationFilePath);
+    const testOutputDir = `${this.outputDir}/${validationFileDir}`;
+    const actualFile = `${this.outputDir}/${validationFilePath}`;
+    const testValidationDir = `${this.validationDir}/${validationFileDir}`;
+    const validationFile = `${this.validationDir}/${validationFilePath}`;
+    mkdirRecursive(testOutputDir);
+    mkdirRecursive(testValidationDir);
+    if (!fs2.existsSync(validationFile)) {
+      writeSnapshotFile(validationFile, actual, true);
+    }
+    writeSnapshotFile(actualFile, actual);
+    return {
+      actual: readSnapshotFile(actualFile),
+      expected: readSnapshotFile(validationFile),
+      actualFile,
+      validationFile
+    };
+  }
+};
 export {
-  normalizeTestName,
-  serializeAsJson,
-  serializeAsText
+  CompositeSerializer,
+  JsonSerializer,
+  TextSerializer,
+  ValidationFileMatcher
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/lib-file-snapshots",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The library agnostic core for testing file snapshots",
   "keywords": [
     "file snapshots"
@@ -33,7 +33,7 @@
   ],
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
-    "@types/node": "22.15.21",
+    "@types/node": "22.15.29",
     "@vitest/coverage-istanbul": "3.1.4",
     "tsup": "8.5.0",
     "typescript": "5.8.3",
@@ -47,6 +47,6 @@
     "test:coverage": "vitest run --coverage",
     "compile": "tsc",
     "build": "tsup",
-    "ci": "biome ci . && pnpm run compile & pnpm run test:coverage && pnpm run build"
+    "ci": "biome ci . && pnpm run compile && pnpm run test:coverage && pnpm run build"
   }
 }