@velumo/core 0.1.0-beta.0

package/src/validation.ts

@@ -0,0 +1,468 @@
+import type { ManifestValidationResult, ValidationIssue } from "./types.js";
+import { validateBackground } from "./background-validation.js";
+import { validateLayoutNode } from "./layout-validation.js";
+import { validateTheme } from "./theme-validation.js";
+import { describeType, issue } from "./validation-issue.js";
+
+type IndexedRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is IndexedRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function typeIssue(
+  path: string,
+  message: string,
+  expected: string,
+  received: unknown,
+): ValidationIssue {
+  return issue(path, "wrong_type", message, {
+    expected,
+    received: describeType(received),
+  });
+}
+
+function requiredIssue(path: string, message: string): ValidationIssue {
+  return issue(path, "required", message, {
+    suggestion: `Provide a value for \`${path}\`.`,
+  });
+}
+
+const CAMERA_EASINGS = [
+  "linear",
+  "ease",
+  "ease-in",
+  "ease-out",
+  "ease-in-out",
+] as const;
+
+const CAMERA_VIEW_KEYS = new Set(["x", "y", "zoom"]);
+const CAMERA_TRANSITION_KEYS = new Set(["duration", "easing"]);
+const CAMERA_STOP_KEYS = new Set(["camera", "transition", "cues", "hold"]);
+
+function isPercent(value: unknown): value is number {
+  return (
+    typeof value === "number" &&
+    Number.isFinite(value) &&
+    value >= 0 &&
+    value <= 100
+  );
+}
+
+function valueIssue(
+  path: string,
+  message: string,
+  received: unknown,
+): ValidationIssue {
+  return issue(path, "invalid_value", message, {
+    received: describeType(received),
+  });
+}
+
+function unknownFieldIssues(
+  record: IndexedRecord,
+  allowed: ReadonlySet<string>,
+  path: string,
+): readonly ValidationIssue[] {
+  return Object.keys(record)
+    .filter((key) => !allowed.has(key))
+    .map((key) =>
+      issue(
+        `${path}.${key}`,
+        "unknown_field",
+        `${path}.${key} is not allowed`,
+        {
+          expected: [...allowed].join(", "),
+          suggestion: `Remove \`${key}\`; it is not a recognized field here.`,
+        },
+      ),
+    );
+}
+
+function validateCameraView(
+  view: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  if (!isRecord(view)) {
+    return [typeIssue(path, `${path} must be an object`, "object", view)];
+  }
+  const issues: ValidationIssue[] = [];
+  for (const axis of ["x", "y"] as const) {
+    if (view[axis] === undefined) {
+      issues.push(
+        requiredIssue(`${path}.${axis}`, `${path}.${axis} is required`),
+      );
+    } else if (!isPercent(view[axis])) {
+      issues.push(
+        valueIssue(
+          `${path}.${axis}`,
+          `${path}.${axis} must be a percentage 0-100`,
+          view[axis],
+        ),
+      );
+    }
+  }
+  if (view.zoom !== undefined) {
+    if (
+      typeof view.zoom !== "number" ||
+      !Number.isFinite(view.zoom) ||
+      view.zoom <= 0
+    ) {
+      issues.push(
+        valueIssue(
+          `${path}.zoom`,
+          `${path}.zoom must be a number > 0`,
+          view.zoom,
+        ),
+      );
+    }
+  }
+  issues.push(...unknownFieldIssues(view, CAMERA_VIEW_KEYS, path));
+  return issues;
+}
+
+function validateCameraTransition(
+  transition: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  if (!isRecord(transition)) {
+    return [typeIssue(path, `${path} must be an object`, "object", transition)];
+  }
+  const issues: ValidationIssue[] = [];
+  if (transition.duration !== undefined) {
+    if (
+      typeof transition.duration !== "number" ||
+      !Number.isFinite(transition.duration) ||
+      transition.duration < 0
+    ) {
+      issues.push(
+        valueIssue(
+          `${path}.duration`,
+          `${path}.duration must be a number >= 0`,
+          transition.duration,
+        ),
+      );
+    }
+  }
+  if (
+    transition.easing !== undefined &&
+    !CAMERA_EASINGS.includes(
+      transition.easing as (typeof CAMERA_EASINGS)[number],
+    )
+  ) {
+    issues.push(
+      issue(
+        `${path}.easing`,
+        "invalid_enum",
+        `${path}.easing must be a known easing`,
+        {
+          expected: CAMERA_EASINGS.join(", "),
+          received:
+            typeof transition.easing === "string"
+              ? transition.easing
+              : describeType(transition.easing),
+          suggestion: `Use one of: ${CAMERA_EASINGS.join(", ")}.`,
+        },
+      ),
+    );
+  }
+  issues.push(...unknownFieldIssues(transition, CAMERA_TRANSITION_KEYS, path));
+  return issues;
+}
+
+function validateCameraStop(
+  stop: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  if (!isRecord(stop)) {
+    return [typeIssue(path, `${path} must be an object`, "object", stop)];
+  }
+  const issues: ValidationIssue[] = [];
+  if (stop.camera === undefined) {
+    issues.push(requiredIssue(`${path}.camera`, `${path}.camera is required`));
+  } else {
+    issues.push(...validateCameraView(stop.camera, `${path}.camera`));
+  }
+  if (stop.transition !== undefined) {
+    issues.push(
+      ...validateCameraTransition(stop.transition, `${path}.transition`),
+    );
+  }
+  if (stop.cues !== undefined) {
+    if (!Array.isArray(stop.cues)) {
+      issues.push(
+        typeIssue(
+          `${path}.cues`,
+          `${path}.cues must be an array`,
+          "array",
+          stop.cues,
+        ),
+      );
+    } else {
+      stop.cues.forEach((cue, cueIndex) => {
+        const cuePath = `${path}.cues[${cueIndex}]`;
+        if (!isRecord(cue)) {
+          issues.push(
+            typeIssue(cuePath, `${cuePath} must be an object`, "object", cue),
+          );
+          return;
+        }
+        if (typeof cue.time !== "number") {
+          issues.push(
+            requiredIssue(`${cuePath}.time`, `${cuePath}.time is required`),
+          );
+        } else if (!Number.isFinite(cue.time) || cue.time < 0) {
+          issues.push(
+            valueIssue(
+              `${cuePath}.time`,
+              `${cuePath}.time must be a finite number >= 0`,
+              cue.time,
+            ),
+          );
+        }
+        if (!isRecord(cue.action) || typeof cue.action.type !== "string") {
+          issues.push(
+            requiredIssue(
+              `${cuePath}.action`,
+              `${cuePath}.action.type is required`,
+            ),
+          );
+        }
+      });
+    }
+  }
+  if (stop.hold !== undefined) {
+    if (
+      typeof stop.hold !== "number" ||
+      !Number.isFinite(stop.hold) ||
+      stop.hold < 0
+    ) {
+      issues.push(
+        valueIssue(
+          `${path}.hold`,
+          `${path}.hold must be a number >= 0`,
+          stop.hold,
+        ),
+      );
+    }
+  }
+  issues.push(...unknownFieldIssues(stop, CAMERA_STOP_KEYS, path));
+  return issues;
+}
+
+function validateCameraPath(
+  value: unknown,
+  path: string,
+): readonly ValidationIssue[] {
+  if (!Array.isArray(value)) {
+    return [typeIssue(path, `${path} must be an array`, "array", value)];
+  }
+  const issues: ValidationIssue[] = [];
+  if (value.length === 0) {
+    issues.push(
+      issue(path, "constraint", `${path} must contain at least one stop`, {
+        suggestion: "Add a cameraStop, or remove the empty cameraPath.",
+      }),
+    );
+    return issues;
+  }
+  value.forEach((stop, index) => {
+    issues.push(...validateCameraStop(stop, `${path}[${index}]`));
+  });
+  return issues;
+}
+
+function validateSlideEntry(
+  entry: unknown,
+  index: number,
+): readonly ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  const path = `slides[${index}]`;
+
+  if (!isRecord(entry)) {
+    return [typeIssue(path, `${path} must be an object`, "object", entry)];
+  }
+
+  if (!isNonEmptyString(entry.id)) {
+    issues.push(requiredIssue(`${path}.id`, `${path}.id is required`));
+  }
+
+  if (entry.layout !== undefined) {
+    issues.push(...validateLayoutNode(entry.layout, `${path}.layout`));
+  }
+
+  if (Array.isArray(entry.layers)) {
+    entry.layers.forEach((layer, layerIndex) => {
+      const layerPath = `${path}.layers[${layerIndex}]`;
+      if (!isRecord(layer)) {
+        issues.push(
+          typeIssue(
+            layerPath,
+            `${layerPath} must be an object`,
+            "object",
+            layer,
+          ),
+        );
+        return;
+      }
+
+      if (!isNonEmptyString(layer.type)) {
+        issues.push(
+          requiredIssue(`${layerPath}.type`, `${layerPath}.type is required`),
+        );
+      }
+    });
+  }
+
+  if (Array.isArray(entry.cues)) {
+    entry.cues.forEach((cue, cueIndex) => {
+      const cuePath = `${path}.cues[${cueIndex}]`;
+      if (!isRecord(cue)) {
+        issues.push(
+          typeIssue(cuePath, `${cuePath} must be an object`, "object", cue),
+        );
+        return;
+      }
+
+      if (typeof cue.time !== "number") {
+        issues.push(
+          requiredIssue(`${cuePath}.time`, `${cuePath}.time is required`),
+        );
+      } else if (!Number.isFinite(cue.time) || cue.time < 0) {
+        issues.push(
+          valueIssue(
+            `${cuePath}.time`,
+            `${cuePath}.time must be a finite number >= 0`,
+            cue.time,
+          ),
+        );
+      }
+    });
+  }
+
+  if (Array.isArray(entry.fragments)) {
+    entry.fragments.forEach((fragment, fragmentIndex) => {
+      const fragmentPath = `${path}.fragments[${fragmentIndex}]`;
+      if (!isRecord(fragment)) {
+        issues.push(
+          typeIssue(
+            fragmentPath,
+            `${fragmentPath} must be an object`,
+            "object",
+            fragment,
+          ),
+        );
+        return;
+      }
+
+      if (!isNonEmptyString(fragment.id)) {
+        issues.push(
+          requiredIssue(`${fragmentPath}.id`, `${fragmentPath}.id is required`),
+        );
+      }
+    });
+  }
+
+  if (entry.background !== undefined) {
+    issues.push(...validateBackground(entry.background, `${path}.background`));
+  }
+
+  if (entry.cameraPath !== undefined) {
+    if (entry.kind !== "scene") {
+      issues.push(
+        issue(
+          `${path}.cameraPath`,
+          "unknown_field",
+          `${path}.cameraPath is only allowed on a scene (kind: "scene")`,
+          {
+            suggestion: `Change this entry's kind to "scene", or remove cameraPath.`,
+          },
+        ),
+      );
+    } else {
+      issues.push(
+        ...validateCameraPath(entry.cameraPath, `${path}.cameraPath`),
+      );
+    }
+  }
+
+  if (entry.chrome !== undefined && typeof entry.chrome !== "boolean") {
+    issues.push(
+      typeIssue(
+        `${path}.chrome`,
+        `${path}.chrome must be a boolean`,
+        "boolean",
+        entry.chrome,
+      ),
+    );
+  }
+
+  return issues;
+}
+
+function collectIssues(manifest: unknown): readonly ValidationIssue[] {
+  if (!isRecord(manifest)) {
+    return [
+      typeIssue("manifest", "manifest must be an object", "object", manifest),
+    ];
+  }
+
+  const issues: ValidationIssue[] = [];
+
+  if (!isRecord(manifest.deck)) {
+    issues.push(
+      typeIssue("deck", "deck must be an object", "object", manifest.deck),
+    );
+  } else {
+    if (!isNonEmptyString(manifest.deck.title)) {
+      issues.push(requiredIssue("deck.title", "deck.title is required"));
+    }
+    if (
+      manifest.deck.watermark !== undefined &&
+      typeof manifest.deck.watermark !== "string"
+    ) {
+      issues.push(
+        typeIssue(
+          "deck.watermark",
+          "deck.watermark must be a string",
+          "string",
+          manifest.deck.watermark,
+        ),
+      );
+    }
+  }
+
+  if (!Array.isArray(manifest.slides)) {
+    issues.push(
+      typeIssue("slides", "slides must be an array", "array", manifest.slides),
+    );
+  } else {
+    manifest.slides.forEach((slide, index) => {
+      issues.push(...validateSlideEntry(slide, index));
+    });
+  }
+
+  if (manifest.theme !== undefined) {
+    issues.push(...validateTheme(manifest.theme));
+  }
+
+  return issues;
+}
+
+export function validateManifest(manifest: unknown): ManifestValidationResult {
+  const issues = collectIssues(manifest);
+
+  return {
+    valid: issues.length === 0,
+    errors: issues.map((current) => current.message),
+    issues,
+  };
+}
+
+export function isValidManifest(manifest: unknown): boolean {
+  return validateManifest(manifest).valid;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo"
+  },
+  "include": ["src/**/*.ts"]
+}