@darksheep/json-schema 0.0.0

package/README.md

@@ -0,0 +1,63 @@
+# @darksheep/package.json
+Fetch the package.json of either; the executing program, or a given package by name.
+This is primarily useful when you're making a package, and you need to find the package.json for the service that is executing your package.
+When using pnpm you need to be cautious to set the root directory correctly.
+
+## Examples
+### Common JS
+```js
+const { getPackageJson } = require('@darksheep/package.json');
+(async () => {
+  const { name, version } = await getPackageJson();
+
+  console.info({ name, version });
+})()
+```
+
+### Module JS
+```js
+import { getPackageJson } from '@darksheep/package.json';
+const { name, version } = await getPackageJson();
+
+console.info({ name, version });
+```
+
+### Sync API
+This api is only useful for commonjs where top level await is not available.
+If you intend on using this inside a module file, please reconsider!
+
+```js
+const { getPackageJson } = require('@darksheep/package.json/sync');
+const { name, version } = getPackageJson();
+
+console.info({ name, version });
+```
+
+## Detailed Docs
+### Async (`@darksheep/package.json`)
+```js
+/** @typedef {import('@darksheep/package.json').PackageJson} PackageJson */
+
+/**
+ *  Attempt to find the package.json for {packageName}
+ *
+ *  @param {string} [packageName] The name of the npm package (the main package if blank)
+ *  @param {string | URL} [root] an optional root url to start from
+ *  @returns  {Promise<PackageJson | null>}
+ */
+export function getPackageJson(packageName, root);
+```
+
+### Sync (`@darksheep/package.json/sync`)
+```js
+/** @typedef {import('@darksheep/package.json').PackageJson} PackageJson */
+
+/**
+ *  Attempt to find the package.json for {packageName} synchronously
+ *
+ *  @param {string} [packageName] The name of the npm package (the main package if blank)
+ *  @param {string | URL} [root] an optional root file url to start from
+ *  @returns  {PackageJson | null}
+ */
+export function getPackageJson(packageName, root);
+```

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@darksheep/json-schema",
+  "version": "0.0.0",
+  "description": "JSON schema validation (with types)",
+  "license": "UNLICENCED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "types",
+    "!*.test.*"
+  ],
+  "scripts": {
+    "prepack": "yarn dlx -q -p typescript tsc",
+    "test": "node --test src/**/*.test.js",
+    "test:watch": "node --watch --test src/**/*.test.js"
+  },
+  "dependencies": {
+    "@darksheep/errors": "",
+    "ajv": "8.17.1",
+    "json-schema-to-ts": "3.1.1"
+  },
+  "engines": {
+    "node": "^20.13.1 || ^22.2.0"
+  }
+}

package/src/errors.js

@@ -0,0 +1,46 @@
+import { BadRequest, InternalServerError } from '@darksheep/errors';
+
+/**
+ * @typedef {(
+ *   & import('@darksheep/errors').ErrorOptions
+ *   & { errors: import('ajv').DefinedError[] }
+ * )} ErrorOptions
+ */
+
+/**
+ * The server will not process the request body not matching the expected request schema.
+ */
+export class RequestSchemaError extends BadRequest {
+  /** @type {import('ajv').DefinedError[]} */
+  errors = [];
+  name = 'RequestSchemaError';
+
+  /**
+   * @param {string} message - The custom message for the http error.
+   * @param {ErrorOptions} options - The custom message for the http error.
+   */
+  constructor(message, { errors, ...options }) {
+    super(message, options);
+
+    this.errors = errors;
+  }
+}
+
+/**
+ * The server tried sending a response that did not match the expected response schema.
+ */
+export class ResponseSchemaError extends InternalServerError {
+  /** @type {import('ajv').DefinedError[]} */
+  errors = [];
+  name = 'ResponseSchemaError';
+
+  /**
+   * @param {string} message - The custom message for the http error.
+   * @param {ErrorOptions} options - The custom message for the http error.
+   */
+  constructor(message, { errors, ...options }) {
+    super(message, options);
+
+    this.errors = errors;
+  }
+}

package/src/index.js

@@ -0,0 +1,32 @@
+/**
+ * @typedef {import('ajv').DefinedError} DefinedError
+ * @typedef {Exclude<import('json-schema-to-ts').JSONSchema, boolean>} JSONSchema
+ * @typedef {import('json-schema-to-ts').FromSchemaOptions} FromSchemaOptions
+ * @typedef {import('json-schema-to-ts').FromSchemaDefaultOptions} FromSchemaDefaultOptions
+ */
+
+/**
+ * @template {JSONSchema} Schema
+ * @template {FromSchemaOptions} [Options=FromSchemaDefaultOptions]
+ * @typedef {import('json-schema-to-ts').FromSchema<Schema, Options>} FromSchema
+ */
+
+/**
+ * @template {JSONSchema} const Schema - The raw schema type.
+ * @param {Schema} schema - The raw JSON schema.
+ * @returns {Schema}
+ */
+export function defineSchema(schema) {
+  return schema;
+}
+
+export {
+  RequestSchemaError,
+  ResponseSchemaError,
+} from './errors.js';
+
+export {
+  validateData,
+  validateRequestBody,
+  validateResponseBody,
+} from './validator.js';

package/src/validator.js

@@ -0,0 +1,122 @@
+import { Ajv } from 'ajv';
+import { RequestSchemaError, ResponseSchemaError } from './errors.js';
+
+/**
+ * @import { DefinedError, AsyncSchema, AsyncValidateFunction, ValidationError } from 'ajv'
+ * @import { FromSchema, JSONSchema } from 'json-schema-to-ts'
+ */
+
+/**
+ * @typedef {(
+ *   & { schema: JSONSchema }
+ * )} ToJsonOptions
+ */
+
+const ajv = new Ajv({
+  allErrors: true,
+  verbose: false,
+  allowUnionTypes: false,
+  multipleOfPrecision: 5,
+  ownProperties: true,
+  strict: true,
+  useDefaults: false,
+});
+
+/**
+ * @type {WeakMap<Exclude<JSONSchema, boolean>, AsyncValidateFunction>}
+ */
+const compiled = new WeakMap();
+
+/**
+ * @param {unknown} input - The value to check.
+ * @returns {input is ValidationError & { errors: DefinedError[] }}
+ */
+function isAjvError(input) {
+  return (
+    input instanceof Error &&
+    'errors' in input &&
+    Array.isArray(input.errors)
+  );
+}
+
+/**
+ * @param {Exclude<JSONSchema, boolean>} schema - The original JSONSchema.
+ * @returns {AsyncValidateFunction}
+ */
+function getValidator(schema) {
+  const Compiled = compiled.get(schema);
+  if (Compiled != null) {
+    return Compiled;
+  }
+
+  const validator = ajv.compile(
+    /** @type {AsyncSchema} */ ({
+      ...schema,
+      $async: true,
+    }),
+  );
+  compiled.set(schema, validator);
+
+  return validator;
+}
+
+/**
+ * @template {Exclude<JSONSchema, boolean>} Schema
+ * @template [Data=FromSchema<Schema>]
+ * @param {Schema} schema - The request body json schema.
+ * @param {unknown} data - The data to validate.
+ * @returns {Promise<Data>}
+ * @throws {ValidationError & { errors: DefinedError[] }}
+ */
+export async function validateData(schema, data) {
+  /** @type {AsyncValidateFunction<Data>} */
+  const validator = getValidator(schema);
+
+  return await validator(data);
+}
+
+/**
+ * @template {Exclude<JSONSchema, boolean>} Schema
+ * @template [Data=FromSchema<Schema>]
+ * @param {Schema} schema - The request body json schema.
+ * @param {unknown} data - The data to validate.
+ * @returns {Promise<Data>}
+ * @throws {RequestSchemaError}
+ */
+export async function validateRequestBody(schema, data) {
+  try {
+    return await validateData(schema, data);
+  } catch (error) {
+    if (isAjvError(error)) {
+      throw new RequestSchemaError(
+        'Request.body does not match Schema',
+        { cause: error, errors: error.errors },
+      );
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * @template {Exclude<JSONSchema, boolean>} Schema
+ * @template [Data=FromSchema<Schema>]
+ * @param {Schema} schema - The response body json schema.
+ * @param {unknown} data - The data to validate.
+ * @returns {Promise<Data>}
+ * @throws {ResponseSchemaError}
+ */
+export async function validateResponseBody(schema, data) {
+  try {
+    return await validateData(schema, data);
+  } catch (error) {
+    if (isAjvError(error)) {
+      throw new ResponseSchemaError(
+        'Response.body does not match Schema',
+        { cause: error, errors: error.errors },
+      );
+    }
+
+    throw error;
+  }
+}

package/types/errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @typedef {(
+ *   & import('@darksheep/errors').ErrorOptions
+ *   & { errors: import('ajv').DefinedError[] }
+ * )} ErrorOptions
+ */
+/**
+ * The server will not process the request body not matching the expected request schema.
+ */
+export class RequestSchemaError extends BadRequest {
+    /**
+     * @param {string} message - The custom message for the http error.
+     * @param {ErrorOptions} options - The custom message for the http error.
+     */
+    constructor(message: string, { errors, ...options }: ErrorOptions);
+    /** @type {import('ajv').DefinedError[]} */
+    errors: import("ajv").DefinedError[];
+}
+/**
+ * The server tried sending a response that did not match the expected response schema.
+ */
+export class ResponseSchemaError extends InternalServerError {
+    /**
+     * @param {string} message - The custom message for the http error.
+     * @param {ErrorOptions} options - The custom message for the http error.
+     */
+    constructor(message: string, { errors, ...options }: ErrorOptions);
+    /** @type {import('ajv').DefinedError[]} */
+    errors: import("ajv").DefinedError[];
+}
+export type ErrorOptions = (import("@darksheep/errors").ErrorOptions & {
+    errors: import("ajv").DefinedError[];
+});
+import { BadRequest } from '@darksheep/errors';
+import { InternalServerError } from '@darksheep/errors';

package/types/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @typedef {import('ajv').DefinedError} DefinedError
+ * @typedef {Exclude<import('json-schema-to-ts').JSONSchema, boolean>} JSONSchema
+ * @typedef {import('json-schema-to-ts').FromSchemaOptions} FromSchemaOptions
+ * @typedef {import('json-schema-to-ts').FromSchemaDefaultOptions} FromSchemaDefaultOptions
+ */
+/**
+ * @template {JSONSchema} Schema
+ * @template {FromSchemaOptions} [Options=FromSchemaDefaultOptions]
+ * @typedef {import('json-schema-to-ts').FromSchema<Schema, Options>} FromSchema
+ */
+/**
+ * @template {JSONSchema} const Schema - The raw schema type.
+ * @param {Schema} schema - The raw JSON schema.
+ * @returns {Schema}
+ */
+export function defineSchema<const Schema extends JSONSchema>(schema: Schema): Schema;
+export type DefinedError = import("ajv").DefinedError;
+export type JSONSchema = Exclude<import("json-schema-to-ts").JSONSchema, boolean>;
+export type FromSchemaOptions = import("json-schema-to-ts").FromSchemaOptions;
+export type FromSchemaDefaultOptions = import("json-schema-to-ts").FromSchemaDefaultOptions;
+export type FromSchema<Schema extends JSONSchema, Options extends FromSchemaOptions = import("json-schema-to-ts").FromSchemaDefaultOptions> = import("json-schema-to-ts").FromSchema<Schema, Options>;
+export { RequestSchemaError, ResponseSchemaError } from "./errors.js";
+export { validateData, validateRequestBody, validateResponseBody } from "./validator.js";

package/types/validator.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @template {Exclude<JSONSchema, boolean>} Schema
+ * @template [Data=FromSchema<Schema>]
+ * @param {Schema} schema - The request body json schema.
+ * @param {unknown} data - The data to validate.
+ * @returns {Promise<Data>}
+ * @throws {ValidationError & { errors: DefinedError[] }}
+ */
+export function validateData<Schema extends Exclude<JSONSchema, boolean>, Data = FromSchema<Schema>>(schema: Schema, data: unknown): Promise<Data>;
+/**
+ * @template {Exclude<JSONSchema, boolean>} Schema
+ * @template [Data=FromSchema<Schema>]
+ * @param {Schema} schema - The request body json schema.
+ * @param {unknown} data - The data to validate.
+ * @returns {Promise<Data>}
+ * @throws {RequestSchemaError}
+ */
+export function validateRequestBody<Schema extends Exclude<JSONSchema, boolean>, Data = FromSchema<Schema>>(schema: Schema, data: unknown): Promise<Data>;
+/**
+ * @template {Exclude<JSONSchema, boolean>} Schema
+ * @template [Data=FromSchema<Schema>]
+ * @param {Schema} schema - The response body json schema.
+ * @param {unknown} data - The data to validate.
+ * @returns {Promise<Data>}
+ * @throws {ResponseSchemaError}
+ */
+export function validateResponseBody<Schema extends Exclude<JSONSchema, boolean>, Data = FromSchema<Schema>>(schema: Schema, data: unknown): Promise<Data>;
+export type ToJsonOptions = ({
+    schema: JSONSchema;
+});
+import type { JSONSchema } from 'json-schema-to-ts';
+import type { FromSchema } from 'json-schema-to-ts';