Initial implementation of JSON Schema Draft-4 and JSON Schema 2019-09

Author: JamesMessinger

src/anchor.ts

@@ -0,0 +1,104 @@
+import { File } from "./file";
+import { JsonSchema } from "./json-schema";
+import { Pointer } from "./pointer";
+import { Resource } from "./resource";
+import { createURL } from "./url";
+import { createError } from "./utils";
+
+const A = 65, Z = 90, a = 97, z = 122, hash = 35;
+const namePattern = /^[a-z][a-z0-9_:.-]*$/i;
+const code = "ERR_INVALID_ANCHOR";
+
+/**
+ * The arguments that can be passed to the `Anchor` constructor
+ */
+export interface AnchorArgs {
+  resource: Resource;
+  locationInFile: string[];
+  name: string | unknown;
+  data: object;
+}
+
+/**
+ * A JSON Schema anchor
+ *
+ * @see http://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.8.2.3
+ */
+export class Anchor {
+  /**
+   * The JSON Schema that this anchor is part of
+   */
+  public schema: JsonSchema;
+
+  /**
+   * The file that contains this anchor
+   */
+  public file: File;
+
+  /**
+   * The JSON Schema resource that contains this anchor
+   */
+  public resource: Resource;
+
+  /**
+   * A pointer to the anchor's location in the file
+   */
+  public locationInFile: Pointer;
+
+  /**
+   * The name of this anchor (e.g. "my-anchor")
+   *
+   * NOTE: According to the 2019-09 spec, anchor names MUST start with a letter
+   */
+  public name: string;
+
+  /**
+   * The anchor object in the JSON Schema
+   */
+  public data: object;
+
+  /**
+   * The absolute URI of this anchor
+   */
+  public uri: URL;
+
+  public constructor(args: AnchorArgs) {
+    let input = args.name;
+
+    if (typeof input !== "string") {
+      let type = typeof input;
+      throw createError(TypeError, `$anchor must be a string, not ${type}.`, { code, type, input });
+    }
+
+    if (input.length === 0) {
+      throw createError(SyntaxError, "$anchor cannot be empty.", { code, input });
+    }
+
+    let firstChar = input.charCodeAt(0);
+    if (firstChar === hash) {
+      throw createError(SyntaxError, "$anchor cannot start with a \"#\" character.", { code, input });
+    }
+    else if (!((firstChar >= A && firstChar <= Z) || (firstChar >= a && firstChar <= z))) {
+      throw createError(SyntaxError, "$anchor must start with a letter.", { code, input });
+    }
+
+    if (!namePattern.test(input)) {
+      throw createError(SyntaxError, "$anchor contains illegal characters.", { code, input });
+    }
+
+    this.schema = args.resource.schema;
+    this.file = args.resource.file;
+    this.resource = args.resource;
+    this.locationInFile = new Pointer(args.locationInFile);
+    this.name = input;
+    this.data = args.data;
+    this.uri = createURL("#" + input, this.resource.uri);
+  }
+
+  /**
+   * Returns the anchor URI
+   */
+  public toString(): string {
+    return `${this.uri || "anchor"}`;
+  }
+}

src/errors/createErrorHandler.ts

@@ -0,0 +1,72 @@
+import { File } from "../file";
+import { Pointer } from "../pointer";
+import { ErrorProps, Helpers } from "./index";
+import { SchemaError } from "./schema-error";
+
+
+export interface ErrorHandlerOptions {
+  file: File;
+  code: string;
+  message?: string;
+  continueOnError?: boolean;
+}
+
+
+/**
+ * Returns a function that handles errors by either recording them or re-throwing them
+ */
+export function createErrorHandler(options: ErrorHandlerOptions): Helpers["handleError"] {
+  let { file, code } = options;
+  options.message = options.message || `Error in ${file}`;
+
+  return function handleError(error: SchemaError, arg2?: string | object, arg3?: object) {
+    // Don't re-wrap errors that have already been handled.
+    // (this happens if the error is caught again in a higher-level catch clause)
+    if (!file.errors.includes(error)) {
+      error = wrapError(error, arg2, arg3);
+      file.errors.push(error);
+    }
+
+    if (!options.continueOnError) {
+      throw error;
+    }
+  };
+
+  /**
+   * Wraps an error in a `SchemaError`
+   */
+  function wrapError(error: SchemaError, arg2?: string | object, arg3?: object) {
+    let message = "";
+    let props: ErrorProps = {};
+
+    // Handle optional arguments and overloads
+    if (typeof arg2 === "object") {
+      props = arg2 as ErrorProps;
+    }
+    else {
+      message = arg2 as string;
+      if (arg3) {
+        props = arg3 as ErrorProps;
+      }
+    }
+
+    let locationInFile = props.locationInFile ? new Pointer(props.locationInFile) : undefined;
+    let originalError = props.originalError || error.originalError || error;
+
+    // Make sure originalError is the most deeply-nested error
+    while ((originalError as ErrorProps).originalError) {
+      originalError = (originalError as ErrorProps).originalError;
+    }
+
+    if (!message) {
+      // Create a default error message
+      message = locationInFile ? `${options.message} at ${locationInFile}` : options.message!;
+    }
+
+    message += `\n  ${error.message}`;
+
+    return new SchemaError(Object.assign({}, originalError, error, props, {
+      code, file, message, locationInFile, originalError
+    }));
+  }
+}

src/errors/index.ts

@@ -0,0 +1,46 @@
+export * from "./createErrorHandler";
+export * from "./schema-error";
+
+
+/**
+ * Additional information that can be added to an error when calling `handleError`
+ */
+export interface ErrorProps {
+  code?: string;
+  locationInFile?: string[];
+  originalError?: Error | unknown;
+  [key: string]: unknown;
+}
+
+
+/**
+ * Helpful information and utilities that are passed to JSON Schema version implementations
+ */
+export interface Helpers {
+  /**
+   * Handles errors appropriately, based on user-specified options.
+   * This may throw the error, or it may simply record the error and return.
+   *
+   * @param error - The error that occurred
+   */
+  handleError(error: Error | unknown): void;
+
+  /**
+   * Handles errors appropriately, based on user-specified options.
+   * This may throw the error, or it may simply record the error and return.
+   *
+   * @param error - The error that occurred
+   * @param props - Additional properties to add to the error when recording or re-throwing it
+   */
+  handleError(error: Error | unknown, props: ErrorProps): void;
+
+  /**
+   * Handles errors appropriately, based on user-specified options.
+   * This may throw the error, or it may simply record the error and return.
+   *
+   * @param error - The error that occurred
+   * @param message - A message to prepend to the original error's message
+   * @param props - Additional properties to add to the error when recording or re-throwing it
+   */
+  handleError(error: Error | unknown, message: string, props?: ErrorProps): void;
+}

src/errors/schema-error.ts

@@ -0,0 +1,55 @@
+import { File } from "../file";
+import { JsonSchema } from "../json-schema";
+import { Pointer } from "../pointer";
+
+
+/**
+ * The arguments that can be passed to the `SchemaError` constructor
+ */
+export interface SchemaErrorArgs {
+  code: string;
+  file: File;
+  message: string;
+  locationInFile?: Pointer;
+  originalError?: Error | unknown;
+  [key: string]: unknown;
+}
+
+
+/**
+ * An error in a JSON Schema
+ */
+export class SchemaError extends Error {
+  /**
+   * A code that indicates the type of error (e.g. ERR_INVALID_URL)
+   */
+  public code!: string;
+
+  /**
+   * The JSON schema, including all files that were successfully read
+   */
+  public schema!: JsonSchema;
+
+  /**
+   * The file that contains or caused this error
+   */
+  public file!: File;
+
+  /**
+   * The location in the file where the error occurred, if known
+   */
+  public locationInFile?: Pointer;
+
+  /**
+   * The original error that occurred
+   */
+  public originalError?: Error;
+
+  public constructor(args: SchemaErrorArgs) {
+    super(args.message);
+    Object.assign(this, args, {
+      schema: args.file.schema
+    });
+    this.name = "SchemaError";
+  }
+}