@powerlines/schema 0.11.81 → 0.11.82

package/dist/metadata.cjs

@@ -0,0 +1,53 @@
+const require_constants = require('./constants.cjs');
+let _stryke_type_checks = require("@stryke/type-checks");
+let _stryke_type_checks_is_set_object = require("@stryke/type-checks/is-set-object");
+
+//#region src/metadata.ts
+/**
+* Applies Powerlines schema metadata onto a JSON Schema fragment.
+*
+* @param schema - The JSON Schema fragment to apply metadata to.
+* @param metadata - The Powerlines schema metadata to apply.
+* @returns A new JSON Schema fragment with the metadata applied.
+*/
+function applyJsonSchemaMetadata(schema, metadata) {
+	if (!metadata || !(0, _stryke_type_checks_is_set_object.isSetObject)(schema)) return schema;
+	const result = { ...schema };
+	const mutableResult = result;
+	for (const key of require_constants.JSON_SCHEMA_METADATA_KEYS) {
+		const value = metadata[key];
+		if (value !== void 0 && value !== null) mutableResult[key] = value;
+	}
+	return result;
+}
+/**
+* Normalizes the JSON Schema `type` keyword to a string array.
+*
+* @remarks
+* This function ensures that the `type` keyword of a JSON Schema fragment is always represented as an array of strings, even if it was originally defined as a single string. This normalization simplifies type checking and processing of JSON Schemas by providing a consistent format for the `type` information.
+*
+* @param schema - The JSON Schema fragment to read types from.
+* @returns An array of JSON Schema primitive type names defined in the `type` keyword, or an empty array if no valid types are found.
+*/
+function readSchemaTypes(schema) {
+	if (!(0, _stryke_type_checks_is_set_object.isSetObject)(schema)) return [];
+	const objectSchema = schema;
+	if (Array.isArray(objectSchema.type)) return objectSchema.type.filter((type) => (0, _stryke_type_checks.isSetString)(type));
+	if ((0, _stryke_type_checks.isSetString)(objectSchema.type) && objectSchema.type !== "object" && objectSchema.type !== "array") return [objectSchema.type];
+	return [];
+}
+/**
+* Returns the primary non-null JSON Schema type name for a fragment.
+*
+* @param schema - The JSON Schema fragment to check.
+* @returns The primary non-null JSON Schema type name, or `undefined` if none is found.
+*/
+function getPrimarySchemaType(schema) {
+	if (!(0, _stryke_type_checks_is_set_object.isSetObject)(schema)) return;
+	return readSchemaTypes(schema).find((type) => type !== "null");
+}
+
+//#endregion
+exports.applyJsonSchemaMetadata = applyJsonSchemaMetadata;
+exports.getPrimarySchemaType = getPrimarySchemaType;
+exports.readSchemaTypes = readSchemaTypes;

package/dist/metadata.d.cts

@@ -0,0 +1,31 @@
+import { JsonSchema, JsonSchemaMetadataKeywords, JsonSchemaPrimitiveType } from "./types.cjs";
+
+//#region src/metadata.d.ts
+/**
+ * Applies Powerlines schema metadata onto a JSON Schema fragment.
+ *
+ * @param schema - The JSON Schema fragment to apply metadata to.
+ * @param metadata - The Powerlines schema metadata to apply.
+ * @returns A new JSON Schema fragment with the metadata applied.
+ */
+declare function applyJsonSchemaMetadata(schema: JsonSchema, metadata: JsonSchemaMetadataKeywords | undefined): JsonSchema;
+/**
+ * Normalizes the JSON Schema `type` keyword to a string array.
+ *
+ * @remarks
+ * This function ensures that the `type` keyword of a JSON Schema fragment is always represented as an array of strings, even if it was originally defined as a single string. This normalization simplifies type checking and processing of JSON Schemas by providing a consistent format for the `type` information.
+ *
+ * @param schema - The JSON Schema fragment to read types from.
+ * @returns An array of JSON Schema primitive type names defined in the `type` keyword, or an empty array if no valid types are found.
+ */
+declare function readSchemaTypes(schema?: JsonSchema): JsonSchemaPrimitiveType[];
+/**
+ * Returns the primary non-null JSON Schema type name for a fragment.
+ *
+ * @param schema - The JSON Schema fragment to check.
+ * @returns The primary non-null JSON Schema type name, or `undefined` if none is found.
+ */
+declare function getPrimarySchemaType(schema?: JsonSchema): JsonSchemaPrimitiveType | undefined;
+//#endregion
+export { applyJsonSchemaMetadata, getPrimarySchemaType, readSchemaTypes };
+//# sourceMappingURL=metadata.d.cts.map

package/dist/metadata.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.cts","names":[],"sources":["../src/metadata.ts"],"mappings":";;;;;AAuCA;;;;;iBAAgB,uBAAA,CACd,MAAA,EAAQ,UAAA,EACR,QAAA,EAAU,0BAAA,eACT,UAAA;;;;;;;;;AAAU;iBA0BG,eAAA,CACd,MAAA,GAAS,UAAA,GACR,uBAAuB;;;;;;;iBA6BV,oBAAA,CACd,MAAA,GAAS,UAAA,GACR,uBAAuB"}

package/dist/metadata.d.mts

@@ -0,0 +1,31 @@
+import { JsonSchema, JsonSchemaMetadataKeywords, JsonSchemaPrimitiveType } from "./types.mjs";
+
+//#region src/metadata.d.ts
+/**
+ * Applies Powerlines schema metadata onto a JSON Schema fragment.
+ *
+ * @param schema - The JSON Schema fragment to apply metadata to.
+ * @param metadata - The Powerlines schema metadata to apply.
+ * @returns A new JSON Schema fragment with the metadata applied.
+ */
+declare function applyJsonSchemaMetadata(schema: JsonSchema, metadata: JsonSchemaMetadataKeywords | undefined): JsonSchema;
+/**
+ * Normalizes the JSON Schema `type` keyword to a string array.
+ *
+ * @remarks
+ * This function ensures that the `type` keyword of a JSON Schema fragment is always represented as an array of strings, even if it was originally defined as a single string. This normalization simplifies type checking and processing of JSON Schemas by providing a consistent format for the `type` information.
+ *
+ * @param schema - The JSON Schema fragment to read types from.
+ * @returns An array of JSON Schema primitive type names defined in the `type` keyword, or an empty array if no valid types are found.
+ */
+declare function readSchemaTypes(schema?: JsonSchema): JsonSchemaPrimitiveType[];
+/**
+ * Returns the primary non-null JSON Schema type name for a fragment.
+ *
+ * @param schema - The JSON Schema fragment to check.
+ * @returns The primary non-null JSON Schema type name, or `undefined` if none is found.
+ */
+declare function getPrimarySchemaType(schema?: JsonSchema): JsonSchemaPrimitiveType | undefined;
+//#endregion
+export { applyJsonSchemaMetadata, getPrimarySchemaType, readSchemaTypes };
+//# sourceMappingURL=metadata.d.mts.map

package/dist/metadata.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.mts","names":[],"sources":["../src/metadata.ts"],"mappings":";;;;;AAuCA;;;;;iBAAgB,uBAAA,CACd,MAAA,EAAQ,UAAA,EACR,QAAA,EAAU,0BAAA,eACT,UAAA;;;;;;;;;AAAU;iBA0BG,eAAA,CACd,MAAA,GAAS,UAAA,GACR,uBAAuB;;;;;;;iBA6BV,oBAAA,CACd,MAAA,GAAS,UAAA,GACR,uBAAuB"}

package/dist/metadata.mjs

@@ -0,0 +1,52 @@
+import { JSON_SCHEMA_METADATA_KEYS } from "./constants.mjs";
+import { isSetString } from "@stryke/type-checks";
+import { isSetObject as isSetObject$1 } from "@stryke/type-checks/is-set-object";
+
+//#region src/metadata.ts
+/**
+* Applies Powerlines schema metadata onto a JSON Schema fragment.
+*
+* @param schema - The JSON Schema fragment to apply metadata to.
+* @param metadata - The Powerlines schema metadata to apply.
+* @returns A new JSON Schema fragment with the metadata applied.
+*/
+function applyJsonSchemaMetadata(schema, metadata) {
+	if (!metadata || !isSetObject$1(schema)) return schema;
+	const result = { ...schema };
+	const mutableResult = result;
+	for (const key of JSON_SCHEMA_METADATA_KEYS) {
+		const value = metadata[key];
+		if (value !== void 0 && value !== null) mutableResult[key] = value;
+	}
+	return result;
+}
+/**
+* Normalizes the JSON Schema `type` keyword to a string array.
+*
+* @remarks
+* This function ensures that the `type` keyword of a JSON Schema fragment is always represented as an array of strings, even if it was originally defined as a single string. This normalization simplifies type checking and processing of JSON Schemas by providing a consistent format for the `type` information.
+*
+* @param schema - The JSON Schema fragment to read types from.
+* @returns An array of JSON Schema primitive type names defined in the `type` keyword, or an empty array if no valid types are found.
+*/
+function readSchemaTypes(schema) {
+	if (!isSetObject$1(schema)) return [];
+	const objectSchema = schema;
+	if (Array.isArray(objectSchema.type)) return objectSchema.type.filter((type) => isSetString(type));
+	if (isSetString(objectSchema.type) && objectSchema.type !== "object" && objectSchema.type !== "array") return [objectSchema.type];
+	return [];
+}
+/**
+* Returns the primary non-null JSON Schema type name for a fragment.
+*
+* @param schema - The JSON Schema fragment to check.
+* @returns The primary non-null JSON Schema type name, or `undefined` if none is found.
+*/
+function getPrimarySchemaType(schema) {
+	if (!isSetObject$1(schema)) return;
+	return readSchemaTypes(schema).find((type) => type !== "null");
+}
+
+//#endregion
+export { applyJsonSchemaMetadata, getPrimarySchemaType, readSchemaTypes };
+//# sourceMappingURL=metadata.mjs.map

package/dist/metadata.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.mjs","names":["isSetObject"],"sources":["../src/metadata.ts"],"sourcesContent":["/* -------------------------------------------------------------------\n\n                   ⚡ Storm Software - Powerlines\n\n This code was released as part of the Powerlines project. Powerlines\n is maintained by Storm Software under the Apache-2.0 license, and is\n free for commercial and private use. For more information, please visit\n our licensing page at https://stormsoftware.com/licenses/projects/powerlines.\n\n Website:                  https://stormsoftware.com\n Repository:               https://github.com/storm-software/powerlines\n Documentation:            https://docs.stormsoftware.com/projects/powerlines\n Contact:                  https://stormsoftware.com/contact\n\n SPDX-License-Identifier:  Apache-2.0\n\n ------------------------------------------------------------------- */\n\nimport { isSetString } from \"@stryke/type-checks\";\nimport { isSetObject } from \"@stryke/type-checks/is-set-object\";\nimport { JSON_SCHEMA_METADATA_KEYS } from \"./constants\";\nimport {\n  JsonSchema,\n  JsonSchemaMetadataKeywords,\n  JsonSchemaPrimitiveType,\n  JsonSchemaType\n} from \"./types\";\n\ninterface JsonSchemaTypeView {\n  type?: JsonSchemaType | readonly JsonSchemaType[];\n}\n\n/**\n * Applies Powerlines schema metadata onto a JSON Schema fragment.\n *\n * @param schema - The JSON Schema fragment to apply metadata to.\n * @param metadata - The Powerlines schema metadata to apply.\n * @returns A new JSON Schema fragment with the metadata applied.\n */\nexport function applyJsonSchemaMetadata(\n  schema: JsonSchema,\n  metadata: JsonSchemaMetadataKeywords | undefined\n): JsonSchema {\n  if (!metadata || !isSetObject(schema)) {\n    return schema;\n  }\n\n  const result: JsonSchema = { ...schema };\n  const mutableResult = result as Record<string, unknown>;\n  for (const key of JSON_SCHEMA_METADATA_KEYS) {\n    const value = metadata[key];\n    if (value !== undefined && value !== null) {\n      mutableResult[key] = value;\n    }\n  }\n\n  return result;\n}\n\n/**\n * Normalizes the JSON Schema `type` keyword to a string array.\n *\n * @remarks\n * This function ensures that the `type` keyword of a JSON Schema fragment is always represented as an array of strings, even if it was originally defined as a single string. This normalization simplifies type checking and processing of JSON Schemas by providing a consistent format for the `type` information.\n *\n * @param schema - The JSON Schema fragment to read types from.\n * @returns An array of JSON Schema primitive type names defined in the `type` keyword, or an empty array if no valid types are found.\n */\nexport function readSchemaTypes(\n  schema?: JsonSchema\n): JsonSchemaPrimitiveType[] {\n  if (!isSetObject(schema)) {\n    return [];\n  }\n\n  const objectSchema = schema as JsonSchemaTypeView;\n\n  if (Array.isArray(objectSchema.type)) {\n    return objectSchema.type.filter(\n      (type: JsonSchemaPrimitiveType): type is JsonSchemaPrimitiveType =>\n        isSetString(type)\n    );\n  }\n  if (\n    isSetString(objectSchema.type) &&\n    objectSchema.type !== \"object\" &&\n    objectSchema.type !== \"array\"\n  ) {\n    return [objectSchema.type];\n  }\n  return [];\n}\n\n/**\n * Returns the primary non-null JSON Schema type name for a fragment.\n *\n * @param schema - The JSON Schema fragment to check.\n * @returns The primary non-null JSON Schema type name, or `undefined` if none is found.\n */\nexport function getPrimarySchemaType(\n  schema?: JsonSchema\n): JsonSchemaPrimitiveType | undefined {\n  if (!isSetObject(schema)) {\n    return undefined;\n  }\n\n  return readSchemaTypes(schema).find(type => type !== \"null\");\n}\n"],"mappings":";;;;;;;;;;;;AAuCA,SAAgB,wBACd,QACA,UACY;CACZ,IAAI,CAAC,YAAY,CAACA,cAAY,MAAM,GAClC,OAAO;CAGT,MAAM,SAAqB,EAAE,GAAG,OAAO;CACvC,MAAM,gBAAgB;CACtB,KAAK,MAAM,OAAO,2BAA2B;EAC3C,MAAM,QAAQ,SAAS;EACvB,IAAI,UAAU,UAAa,UAAU,MACnC,cAAc,OAAO;CAEzB;CAEA,OAAO;AACT;;;;;;;;;;AAWA,SAAgB,gBACd,QAC2B;CAC3B,IAAI,CAACA,cAAY,MAAM,GACrB,OAAO,CAAC;CAGV,MAAM,eAAe;CAErB,IAAI,MAAM,QAAQ,aAAa,IAAI,GACjC,OAAO,aAAa,KAAK,QACtB,SACC,YAAY,IAAI,CACpB;CAEF,IACE,YAAY,aAAa,IAAI,KAC7B,aAAa,SAAS,YACtB,aAAa,SAAS,SAEtB,OAAO,CAAC,aAAa,IAAI;CAE3B,OAAO,CAAC;AACV;;;;;;;AAQA,SAAgB,qBACd,QACqC;CACrC,IAAI,CAACA,cAAY,MAAM,GACrB;CAGF,OAAO,gBAAgB,MAAM,EAAE,MAAK,SAAQ,SAAS,MAAM;AAC7D"}

package/dist/persistence.cjs

@@ -0,0 +1,74 @@
+const require_type_checks = require('./type-checks.cjs');
+const require_extract = require('./extract.cjs');
+let _stryke_path_join = require("@stryke/path/join");
+
+//#region src/persistence.ts
+/**
+* A helper function to get the cache directory path for storing schemas. This function takes a context object as input and returns the path to the cache directory where schemas are stored. The cache directory is constructed by joining the `cachePath` property from the context with a subdirectory named "schemas". This function is useful for centralizing the logic for determining where schema files should be cached, ensuring that all schema-related file operations use a consistent location for storing and retrieving cached schemas.
+*
+* @param context - The context object providing access to the cache path.
+* @returns The path to the cache directory for storing schemas, constructed by joining the context's `cachePath` with the "schemas" subdirectory.
+*/
+function getCacheDirectory(context) {
+	return (0, _stryke_path_join.joinPaths)(context.cachePath, "schemas");
+}
+/**
+* A helper function to get the file path for a cached schema based on the provided context and schema input. This function first extracts the variant and hash from the input schema using the `extractVariant` and `extractHash` functions, respectively. It then constructs the file path to the cached schema JSON file by joining the cache directory path (obtained from the `getCacheDirectory` function) with a filename derived from the extracted hash. The resulting file path points to where the cached schema should be stored or retrieved from in the file system. This function is essential for ensuring that all operations related to caching schemas use a consistent method for determining the correct file path based on the schema's unique identifier (hash).
+*
+* @param context - The context object providing access to the cache path.
+* @param input - The input schema from which to extract the variant and hash for constructing the cache file path.
+* @returns The file path to the cached schema JSON file, constructed by joining the cache directory path with a filename derived from the extracted hash of the schema input.
+*/
+function getCacheFilePath(context, input) {
+	const hash = require_extract.extractHash(require_extract.extractVariant(input), input);
+	return (0, _stryke_path_join.joinPaths)(getCacheDirectory(context), `${hash}.json`);
+}
+/**
+* Writes a given schema to the file system using the provided context. This function first checks if the input is a valid schema using the `isSchema` type guard. If the input is not a valid schema, it throws an error indicating that the provided input is invalid. If the input is valid, it proceeds to write the schema to a JSON file in the cache directory specified by the context. The file is named using the hash of the schema to ensure uniqueness and easy retrieval in future operations. The schema is serialized to JSON format before being written to the file system. This function is asynchronous and returns a promise that resolves once the writing operation is complete.
+*
+* @param context - The context object providing access to the file system and cache path.
+* @param schema - The schema to be written to the file system, which must be a valid schema object containing a `variant`, `schema`, and `hash` property.
+* @throws Will throw an error if the provided input is not a valid schema.
+*/
+async function writeSchema(context, schema) {
+	if (!require_type_checks.isSchema(schema)) throw new Error(`The provided input is not a valid schema. A valid schema must have a "variant" property indicating the type of the input and a "schema" property containing the parsed JSON Schema object.`);
+	await context.fs.write(getCacheFilePath(context, schema), JSON.stringify(schema.schema));
+}
+/**
+* A helper function to read a schema from the file system using the provided context. This function first extracts the variant and hash from the input schema using the `extractVariant` and `extractHash` functions, respectively. It then constructs the file path to the cached schema JSON file based on the cache path provided in the context and the extracted hash. The function checks if the file exists in the cache; if it does not exist, it returns `undefined`. If the file exists, it reads the contents of the file, parses it as JSON, and returns the resulting object. This function is asynchronous and returns a promise that resolves to either the parsed schema object or `undefined` if the schema is not found in the cache.
+*
+* @param context - The context object providing access to the file system and cache path.
+* @param input - The input schema from which to extract the variant and hash for locating the cached schema file.
+* @returns A promise that resolves to the parsed schema object if found in the cache, or `undefined` if the schema does not exist in the cache.
+*/
+async function readSchemaSafe(context, input) {
+	const cacheFilePath = getCacheFilePath(context, input);
+	if (!await context.fs.exists(cacheFilePath)) return;
+	const data = await context.fs.read(cacheFilePath);
+	if (!data) return;
+	return JSON.parse(data);
+}
+/**
+* Reads a schema from the file system using the provided context and input. This function first attempts to read the schema using the `readSchemaSafe` helper function, which returns `undefined` if the schema is not found in the cache. If the schema is not found, this function throws an error indicating that the schema with the specified variant and hash does not exist in the cache. The error message suggests that this may be due to a missing or corrupted cache file, or because the schema has not been written to the cache yet. It advises ensuring that the schema is properly written to the cache before attempting to read it. If the schema is successfully read from the cache, it is returned as a parsed object. This function is asynchronous and returns a promise that resolves to the parsed schema object if found, or throws an error if the schema is not found in the cache.
+*
+* @param context - The context object providing access to the file system and cache path.
+* @param input - The input schema from which to extract the variant and hash for locating the cached schema file.
+* @returns A promise that resolves to the parsed schema object if found in the cache, or throws an error if the schema does not exist in the cache.
+* @throws Will throw an error if the schema with the specified variant and hash does not exist in the cache.
+*/
+async function readSchema(context, input) {
+	const schema = await readSchemaSafe(context, input);
+	if (!schema) {
+		const variant = require_extract.extractVariant(input);
+		const hash = require_extract.extractHash(variant, input);
+		throw new Error(`The ${variant} schema with hash "${hash}" does not exist in the cache. This may be due to a missing or corrupted cache file, or because the schema has not been written to the cache yet. Please ensure that the schema is properly written to the cache before attempting to read it.`);
+	}
+	return schema;
+}
+
+//#endregion
+exports.getCacheDirectory = getCacheDirectory;
+exports.getCacheFilePath = getCacheFilePath;
+exports.readSchema = readSchema;
+exports.readSchemaSafe = readSchemaSafe;
+exports.writeSchema = writeSchema;

package/dist/persistence.d.cts

@@ -0,0 +1,47 @@
+import { Schema, SchemaInput } from "./types.cjs";
+import { Context } from "@powerlines/core";
+
+//#region src/persistence.d.ts
+/**
+ * A helper function to get the cache directory path for storing schemas. This function takes a context object as input and returns the path to the cache directory where schemas are stored. The cache directory is constructed by joining the `cachePath` property from the context with a subdirectory named "schemas". This function is useful for centralizing the logic for determining where schema files should be cached, ensuring that all schema-related file operations use a consistent location for storing and retrieving cached schemas.
+ *
+ * @param context - The context object providing access to the cache path.
+ * @returns The path to the cache directory for storing schemas, constructed by joining the context's `cachePath` with the "schemas" subdirectory.
+ */
+declare function getCacheDirectory(context: Context): string;
+/**
+ * A helper function to get the file path for a cached schema based on the provided context and schema input. This function first extracts the variant and hash from the input schema using the `extractVariant` and `extractHash` functions, respectively. It then constructs the file path to the cached schema JSON file by joining the cache directory path (obtained from the `getCacheDirectory` function) with a filename derived from the extracted hash. The resulting file path points to where the cached schema should be stored or retrieved from in the file system. This function is essential for ensuring that all operations related to caching schemas use a consistent method for determining the correct file path based on the schema's unique identifier (hash).
+ *
+ * @param context - The context object providing access to the cache path.
+ * @param input - The input schema from which to extract the variant and hash for constructing the cache file path.
+ * @returns The file path to the cached schema JSON file, constructed by joining the cache directory path with a filename derived from the extracted hash of the schema input.
+ */
+declare function getCacheFilePath(context: Context, input: SchemaInput): string;
+/**
+ * Writes a given schema to the file system using the provided context. This function first checks if the input is a valid schema using the `isSchema` type guard. If the input is not a valid schema, it throws an error indicating that the provided input is invalid. If the input is valid, it proceeds to write the schema to a JSON file in the cache directory specified by the context. The file is named using the hash of the schema to ensure uniqueness and easy retrieval in future operations. The schema is serialized to JSON format before being written to the file system. This function is asynchronous and returns a promise that resolves once the writing operation is complete.
+ *
+ * @param context - The context object providing access to the file system and cache path.
+ * @param schema - The schema to be written to the file system, which must be a valid schema object containing a `variant`, `schema`, and `hash` property.
+ * @throws Will throw an error if the provided input is not a valid schema.
+ */
+declare function writeSchema(context: Context, schema: Schema): Promise<void>;
+/**
+ * A helper function to read a schema from the file system using the provided context. This function first extracts the variant and hash from the input schema using the `extractVariant` and `extractHash` functions, respectively. It then constructs the file path to the cached schema JSON file based on the cache path provided in the context and the extracted hash. The function checks if the file exists in the cache; if it does not exist, it returns `undefined`. If the file exists, it reads the contents of the file, parses it as JSON, and returns the resulting object. This function is asynchronous and returns a promise that resolves to either the parsed schema object or `undefined` if the schema is not found in the cache.
+ *
+ * @param context - The context object providing access to the file system and cache path.
+ * @param input - The input schema from which to extract the variant and hash for locating the cached schema file.
+ * @returns A promise that resolves to the parsed schema object if found in the cache, or `undefined` if the schema does not exist in the cache.
+ */
+declare function readSchemaSafe(context: Context, input: SchemaInput): Promise<Schema | undefined>;
+/**
+ * Reads a schema from the file system using the provided context and input. This function first attempts to read the schema using the `readSchemaSafe` helper function, which returns `undefined` if the schema is not found in the cache. If the schema is not found, this function throws an error indicating that the schema with the specified variant and hash does not exist in the cache. The error message suggests that this may be due to a missing or corrupted cache file, or because the schema has not been written to the cache yet. It advises ensuring that the schema is properly written to the cache before attempting to read it. If the schema is successfully read from the cache, it is returned as a parsed object. This function is asynchronous and returns a promise that resolves to the parsed schema object if found, or throws an error if the schema is not found in the cache.
+ *
+ * @param context - The context object providing access to the file system and cache path.
+ * @param input - The input schema from which to extract the variant and hash for locating the cached schema file.
+ * @returns A promise that resolves to the parsed schema object if found in the cache, or throws an error if the schema does not exist in the cache.
+ * @throws Will throw an error if the schema with the specified variant and hash does not exist in the cache.
+ */
+declare function readSchema(context: Context, input: SchemaInput): Promise<Schema>;
+//#endregion
+export { getCacheDirectory, getCacheFilePath, readSchema, readSchemaSafe, writeSchema };
+//# sourceMappingURL=persistence.d.cts.map

package/dist/persistence.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.cts","names":[],"sources":["../src/persistence.ts"],"mappings":";;;;;;AA8BA;;;;iBAAgB,iBAAA,CAAkB,OAAgB,EAAP,OAAO;AAWlD;;;;;;;AAAA,iBAAgB,gBAAA,CAAiB,OAAA,EAAS,OAAA,EAAS,KAAA,EAAO,WAAW;;AAAA;AAcrE;;;;;iBAAsB,WAAA,CAAY,OAAA,EAAS,OAAA,EAAS,MAAA,EAAQ,MAAA,GAAM,OAAA;;;;;;;;iBAoB5C,cAAA,CACpB,OAAA,EAAS,OAAA,EACT,KAAA,EAAO,WAAA,GACN,OAAA,CAAQ,MAAA;AAvBuD;AAoBlE;;;;;;;AApBkE,iBA6C5C,UAAA,CACpB,OAAA,EAAS,OAAA,EACT,KAAA,EAAO,WAAA,GACN,OAAA,CAAQ,MAAA"}

package/dist/persistence.d.mts

@@ -0,0 +1,47 @@
+import { Schema, SchemaInput } from "./types.mjs";
+import { Context } from "@powerlines/core";
+
+//#region src/persistence.d.ts
+/**
+ * A helper function to get the cache directory path for storing schemas. This function takes a context object as input and returns the path to the cache directory where schemas are stored. The cache directory is constructed by joining the `cachePath` property from the context with a subdirectory named "schemas". This function is useful for centralizing the logic for determining where schema files should be cached, ensuring that all schema-related file operations use a consistent location for storing and retrieving cached schemas.
+ *
+ * @param context - The context object providing access to the cache path.
+ * @returns The path to the cache directory for storing schemas, constructed by joining the context's `cachePath` with the "schemas" subdirectory.
+ */
+declare function getCacheDirectory(context: Context): string;
+/**
+ * A helper function to get the file path for a cached schema based on the provided context and schema input. This function first extracts the variant and hash from the input schema using the `extractVariant` and `extractHash` functions, respectively. It then constructs the file path to the cached schema JSON file by joining the cache directory path (obtained from the `getCacheDirectory` function) with a filename derived from the extracted hash. The resulting file path points to where the cached schema should be stored or retrieved from in the file system. This function is essential for ensuring that all operations related to caching schemas use a consistent method for determining the correct file path based on the schema's unique identifier (hash).
+ *
+ * @param context - The context object providing access to the cache path.
+ * @param input - The input schema from which to extract the variant and hash for constructing the cache file path.
+ * @returns The file path to the cached schema JSON file, constructed by joining the cache directory path with a filename derived from the extracted hash of the schema input.
+ */
+declare function getCacheFilePath(context: Context, input: SchemaInput): string;
+/**
+ * Writes a given schema to the file system using the provided context. This function first checks if the input is a valid schema using the `isSchema` type guard. If the input is not a valid schema, it throws an error indicating that the provided input is invalid. If the input is valid, it proceeds to write the schema to a JSON file in the cache directory specified by the context. The file is named using the hash of the schema to ensure uniqueness and easy retrieval in future operations. The schema is serialized to JSON format before being written to the file system. This function is asynchronous and returns a promise that resolves once the writing operation is complete.
+ *
+ * @param context - The context object providing access to the file system and cache path.
+ * @param schema - The schema to be written to the file system, which must be a valid schema object containing a `variant`, `schema`, and `hash` property.
+ * @throws Will throw an error if the provided input is not a valid schema.
+ */
+declare function writeSchema(context: Context, schema: Schema): Promise<void>;
+/**
+ * A helper function to read a schema from the file system using the provided context. This function first extracts the variant and hash from the input schema using the `extractVariant` and `extractHash` functions, respectively. It then constructs the file path to the cached schema JSON file based on the cache path provided in the context and the extracted hash. The function checks if the file exists in the cache; if it does not exist, it returns `undefined`. If the file exists, it reads the contents of the file, parses it as JSON, and returns the resulting object. This function is asynchronous and returns a promise that resolves to either the parsed schema object or `undefined` if the schema is not found in the cache.
+ *
+ * @param context - The context object providing access to the file system and cache path.
+ * @param input - The input schema from which to extract the variant and hash for locating the cached schema file.
+ * @returns A promise that resolves to the parsed schema object if found in the cache, or `undefined` if the schema does not exist in the cache.
+ */
+declare function readSchemaSafe(context: Context, input: SchemaInput): Promise<Schema | undefined>;
+/**
+ * Reads a schema from the file system using the provided context and input. This function first attempts to read the schema using the `readSchemaSafe` helper function, which returns `undefined` if the schema is not found in the cache. If the schema is not found, this function throws an error indicating that the schema with the specified variant and hash does not exist in the cache. The error message suggests that this may be due to a missing or corrupted cache file, or because the schema has not been written to the cache yet. It advises ensuring that the schema is properly written to the cache before attempting to read it. If the schema is successfully read from the cache, it is returned as a parsed object. This function is asynchronous and returns a promise that resolves to the parsed schema object if found, or throws an error if the schema is not found in the cache.
+ *
+ * @param context - The context object providing access to the file system and cache path.
+ * @param input - The input schema from which to extract the variant and hash for locating the cached schema file.
+ * @returns A promise that resolves to the parsed schema object if found in the cache, or throws an error if the schema does not exist in the cache.
+ * @throws Will throw an error if the schema with the specified variant and hash does not exist in the cache.
+ */
+declare function readSchema(context: Context, input: SchemaInput): Promise<Schema>;
+//#endregion
+export { getCacheDirectory, getCacheFilePath, readSchema, readSchemaSafe, writeSchema };
+//# sourceMappingURL=persistence.d.mts.map

package/dist/persistence.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.mts","names":[],"sources":["../src/persistence.ts"],"mappings":";;;;;;AA8BA;;;;iBAAgB,iBAAA,CAAkB,OAAgB,EAAP,OAAO;AAWlD;;;;;;;AAAA,iBAAgB,gBAAA,CAAiB,OAAA,EAAS,OAAA,EAAS,KAAA,EAAO,WAAW;;AAAA;AAcrE;;;;;iBAAsB,WAAA,CAAY,OAAA,EAAS,OAAA,EAAS,MAAA,EAAQ,MAAA,GAAM,OAAA;;;;;;;;iBAoB5C,cAAA,CACpB,OAAA,EAAS,OAAA,EACT,KAAA,EAAO,WAAA,GACN,OAAA,CAAQ,MAAA;AAvBuD;AAoBlE;;;;;;;AApBkE,iBA6C5C,UAAA,CACpB,OAAA,EAAS,OAAA,EACT,KAAA,EAAO,WAAA,GACN,OAAA,CAAQ,MAAA"}

package/dist/persistence.mjs

@@ -0,0 +1,71 @@
+import { isSchema } from "./type-checks.mjs";
+import { extractHash, extractVariant } from "./extract.mjs";
+import { joinPaths } from "@stryke/path/join";
+
+//#region src/persistence.ts
+/**
+* A helper function to get the cache directory path for storing schemas. This function takes a context object as input and returns the path to the cache directory where schemas are stored. The cache directory is constructed by joining the `cachePath` property from the context with a subdirectory named "schemas". This function is useful for centralizing the logic for determining where schema files should be cached, ensuring that all schema-related file operations use a consistent location for storing and retrieving cached schemas.
+*
+* @param context - The context object providing access to the cache path.
+* @returns The path to the cache directory for storing schemas, constructed by joining the context's `cachePath` with the "schemas" subdirectory.
+*/
+function getCacheDirectory(context) {
+	return joinPaths(context.cachePath, "schemas");
+}
+/**
+* A helper function to get the file path for a cached schema based on the provided context and schema input. This function first extracts the variant and hash from the input schema using the `extractVariant` and `extractHash` functions, respectively. It then constructs the file path to the cached schema JSON file by joining the cache directory path (obtained from the `getCacheDirectory` function) with a filename derived from the extracted hash. The resulting file path points to where the cached schema should be stored or retrieved from in the file system. This function is essential for ensuring that all operations related to caching schemas use a consistent method for determining the correct file path based on the schema's unique identifier (hash).
+*
+* @param context - The context object providing access to the cache path.
+* @param input - The input schema from which to extract the variant and hash for constructing the cache file path.
+* @returns The file path to the cached schema JSON file, constructed by joining the cache directory path with a filename derived from the extracted hash of the schema input.
+*/
+function getCacheFilePath(context, input) {
+	const hash = extractHash(extractVariant(input), input);
+	return joinPaths(getCacheDirectory(context), `${hash}.json`);
+}
+/**
+* Writes a given schema to the file system using the provided context. This function first checks if the input is a valid schema using the `isSchema` type guard. If the input is not a valid schema, it throws an error indicating that the provided input is invalid. If the input is valid, it proceeds to write the schema to a JSON file in the cache directory specified by the context. The file is named using the hash of the schema to ensure uniqueness and easy retrieval in future operations. The schema is serialized to JSON format before being written to the file system. This function is asynchronous and returns a promise that resolves once the writing operation is complete.
+*
+* @param context - The context object providing access to the file system and cache path.
+* @param schema - The schema to be written to the file system, which must be a valid schema object containing a `variant`, `schema`, and `hash` property.
+* @throws Will throw an error if the provided input is not a valid schema.
+*/
+async function writeSchema(context, schema) {
+	if (!isSchema(schema)) throw new Error(`The provided input is not a valid schema. A valid schema must have a "variant" property indicating the type of the input and a "schema" property containing the parsed JSON Schema object.`);
+	await context.fs.write(getCacheFilePath(context, schema), JSON.stringify(schema.schema));
+}
+/**
+* A helper function to read a schema from the file system using the provided context. This function first extracts the variant and hash from the input schema using the `extractVariant` and `extractHash` functions, respectively. It then constructs the file path to the cached schema JSON file based on the cache path provided in the context and the extracted hash. The function checks if the file exists in the cache; if it does not exist, it returns `undefined`. If the file exists, it reads the contents of the file, parses it as JSON, and returns the resulting object. This function is asynchronous and returns a promise that resolves to either the parsed schema object or `undefined` if the schema is not found in the cache.
+*
+* @param context - The context object providing access to the file system and cache path.
+* @param input - The input schema from which to extract the variant and hash for locating the cached schema file.
+* @returns A promise that resolves to the parsed schema object if found in the cache, or `undefined` if the schema does not exist in the cache.
+*/
+async function readSchemaSafe(context, input) {
+	const cacheFilePath = getCacheFilePath(context, input);
+	if (!await context.fs.exists(cacheFilePath)) return;
+	const data = await context.fs.read(cacheFilePath);
+	if (!data) return;
+	return JSON.parse(data);
+}
+/**
+* Reads a schema from the file system using the provided context and input. This function first attempts to read the schema using the `readSchemaSafe` helper function, which returns `undefined` if the schema is not found in the cache. If the schema is not found, this function throws an error indicating that the schema with the specified variant and hash does not exist in the cache. The error message suggests that this may be due to a missing or corrupted cache file, or because the schema has not been written to the cache yet. It advises ensuring that the schema is properly written to the cache before attempting to read it. If the schema is successfully read from the cache, it is returned as a parsed object. This function is asynchronous and returns a promise that resolves to the parsed schema object if found, or throws an error if the schema is not found in the cache.
+*
+* @param context - The context object providing access to the file system and cache path.
+* @param input - The input schema from which to extract the variant and hash for locating the cached schema file.
+* @returns A promise that resolves to the parsed schema object if found in the cache, or throws an error if the schema does not exist in the cache.
+* @throws Will throw an error if the schema with the specified variant and hash does not exist in the cache.
+*/
+async function readSchema(context, input) {
+	const schema = await readSchemaSafe(context, input);
+	if (!schema) {
+		const variant = extractVariant(input);
+		const hash = extractHash(variant, input);
+		throw new Error(`The ${variant} schema with hash "${hash}" does not exist in the cache. This may be due to a missing or corrupted cache file, or because the schema has not been written to the cache yet. Please ensure that the schema is properly written to the cache before attempting to read it.`);
+	}
+	return schema;
+}
+
+//#endregion
+export { getCacheDirectory, getCacheFilePath, readSchema, readSchemaSafe, writeSchema };
+//# sourceMappingURL=persistence.mjs.map

package/dist/persistence.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.mjs","names":[],"sources":["../src/persistence.ts"],"sourcesContent":["/* -------------------------------------------------------------------\n\n                   ⚡ Storm Software - Powerlines\n\n This code was released as part of the Powerlines project. Powerlines\n is maintained by Storm Software under the Apache-2.0 license, and is\n free for commercial and private use. For more information, please visit\n our licensing page at https://stormsoftware.com/licenses/projects/powerlines.\n\n Website:                  https://stormsoftware.com\n Repository:               https://github.com/storm-software/powerlines\n Documentation:            https://docs.stormsoftware.com/projects/powerlines\n Contact:                  https://stormsoftware.com/contact\n\n SPDX-License-Identifier:  Apache-2.0\n\n ------------------------------------------------------------------- */\n\nimport type { Context } from \"@powerlines/core\";\nimport { joinPaths } from \"@stryke/path/join\";\nimport { extractHash, extractVariant } from \"./extract\";\nimport { isSchema } from \"./type-checks\";\nimport { Schema, SchemaInput } from \"./types\";\n\n/**\n * A helper function to get the cache directory path for storing schemas. This function takes a context object as input and returns the path to the cache directory where schemas are stored. The cache directory is constructed by joining the `cachePath` property from the context with a subdirectory named \"schemas\". This function is useful for centralizing the logic for determining where schema files should be cached, ensuring that all schema-related file operations use a consistent location for storing and retrieving cached schemas.\n *\n * @param context - The context object providing access to the cache path.\n * @returns The path to the cache directory for storing schemas, constructed by joining the context's `cachePath` with the \"schemas\" subdirectory.\n */\nexport function getCacheDirectory(context: Context): string {\n  return joinPaths(context.cachePath, \"schemas\");\n}\n\n/**\n * A helper function to get the file path for a cached schema based on the provided context and schema input. This function first extracts the variant and hash from the input schema using the `extractVariant` and `extractHash` functions, respectively. It then constructs the file path to the cached schema JSON file by joining the cache directory path (obtained from the `getCacheDirectory` function) with a filename derived from the extracted hash. The resulting file path points to where the cached schema should be stored or retrieved from in the file system. This function is essential for ensuring that all operations related to caching schemas use a consistent method for determining the correct file path based on the schema's unique identifier (hash).\n *\n * @param context - The context object providing access to the cache path.\n * @param input - The input schema from which to extract the variant and hash for constructing the cache file path.\n * @returns The file path to the cached schema JSON file, constructed by joining the cache directory path with a filename derived from the extracted hash of the schema input.\n */\nexport function getCacheFilePath(context: Context, input: SchemaInput): string {\n  const variant = extractVariant(input);\n  const hash = extractHash(variant, input);\n\n  return joinPaths(getCacheDirectory(context), `${hash}.json`);\n}\n\n/**\n * Writes a given schema to the file system using the provided context. This function first checks if the input is a valid schema using the `isSchema` type guard. If the input is not a valid schema, it throws an error indicating that the provided input is invalid. If the input is valid, it proceeds to write the schema to a JSON file in the cache directory specified by the context. The file is named using the hash of the schema to ensure uniqueness and easy retrieval in future operations. The schema is serialized to JSON format before being written to the file system. This function is asynchronous and returns a promise that resolves once the writing operation is complete.\n *\n * @param context - The context object providing access to the file system and cache path.\n * @param schema - The schema to be written to the file system, which must be a valid schema object containing a `variant`, `schema`, and `hash` property.\n * @throws Will throw an error if the provided input is not a valid schema.\n */\nexport async function writeSchema(context: Context, schema: Schema) {\n  if (!isSchema(schema)) {\n    throw new Error(\n      `The provided input is not a valid schema. A valid schema must have a \"variant\" property indicating the type of the input and a \"schema\" property containing the parsed JSON Schema object.`\n    );\n  }\n\n  await context.fs.write(\n    getCacheFilePath(context, schema),\n    JSON.stringify(schema.schema)\n  );\n}\n\n/**\n * A helper function to read a schema from the file system using the provided context. This function first extracts the variant and hash from the input schema using the `extractVariant` and `extractHash` functions, respectively. It then constructs the file path to the cached schema JSON file based on the cache path provided in the context and the extracted hash. The function checks if the file exists in the cache; if it does not exist, it returns `undefined`. If the file exists, it reads the contents of the file, parses it as JSON, and returns the resulting object. This function is asynchronous and returns a promise that resolves to either the parsed schema object or `undefined` if the schema is not found in the cache.\n *\n * @param context - The context object providing access to the file system and cache path.\n * @param input - The input schema from which to extract the variant and hash for locating the cached schema file.\n * @returns A promise that resolves to the parsed schema object if found in the cache, or `undefined` if the schema does not exist in the cache.\n */\nexport async function readSchemaSafe(\n  context: Context,\n  input: SchemaInput\n): Promise<Schema | undefined> {\n  const cacheFilePath = getCacheFilePath(context, input);\n  if (!(await context.fs.exists(cacheFilePath))) {\n    return undefined;\n  }\n\n  const data = await context.fs.read(cacheFilePath);\n  if (!data) {\n    return undefined;\n  }\n\n  return JSON.parse(data);\n}\n\n/**\n * Reads a schema from the file system using the provided context and input. This function first attempts to read the schema using the `readSchemaSafe` helper function, which returns `undefined` if the schema is not found in the cache. If the schema is not found, this function throws an error indicating that the schema with the specified variant and hash does not exist in the cache. The error message suggests that this may be due to a missing or corrupted cache file, or because the schema has not been written to the cache yet. It advises ensuring that the schema is properly written to the cache before attempting to read it. If the schema is successfully read from the cache, it is returned as a parsed object. This function is asynchronous and returns a promise that resolves to the parsed schema object if found, or throws an error if the schema is not found in the cache.\n *\n * @param context - The context object providing access to the file system and cache path.\n * @param input - The input schema from which to extract the variant and hash for locating the cached schema file.\n * @returns A promise that resolves to the parsed schema object if found in the cache, or throws an error if the schema does not exist in the cache.\n * @throws Will throw an error if the schema with the specified variant and hash does not exist in the cache.\n */\nexport async function readSchema(\n  context: Context,\n  input: SchemaInput\n): Promise<Schema> {\n  const schema = await readSchemaSafe(context, input);\n  if (!schema) {\n    const variant = extractVariant(input);\n    const hash = extractHash(variant, input);\n\n    throw new Error(\n      `The ${variant} schema with hash \"${\n        hash\n      }\" does not exist in the cache. This may be due to a missing or corrupted cache file, or because the schema has not been written to the cache yet. Please ensure that the schema is properly written to the cache before attempting to read it.`\n    );\n  }\n\n  return schema;\n}\n"],"mappings":";;;;;;;;;;;AA8BA,SAAgB,kBAAkB,SAA0B;CAC1D,OAAO,UAAU,QAAQ,WAAW,SAAS;AAC/C;;;;;;;;AASA,SAAgB,iBAAiB,SAAkB,OAA4B;CAE7E,MAAM,OAAO,YADG,eAAe,KACA,GAAG,KAAK;CAEvC,OAAO,UAAU,kBAAkB,OAAO,GAAG,GAAG,KAAK,MAAM;AAC7D;;;;;;;;AASA,eAAsB,YAAY,SAAkB,QAAgB;CAClE,IAAI,CAAC,SAAS,MAAM,GAClB,MAAM,IAAI,MACR,4LACF;CAGF,MAAM,QAAQ,GAAG,MACf,iBAAiB,SAAS,MAAM,GAChC,KAAK,UAAU,OAAO,MAAM,CAC9B;AACF;;;;;;;;AASA,eAAsB,eACpB,SACA,OAC6B;CAC7B,MAAM,gBAAgB,iBAAiB,SAAS,KAAK;CACrD,IAAI,CAAE,MAAM,QAAQ,GAAG,OAAO,aAAa,GACzC;CAGF,MAAM,OAAO,MAAM,QAAQ,GAAG,KAAK,aAAa;CAChD,IAAI,CAAC,MACH;CAGF,OAAO,KAAK,MAAM,IAAI;AACxB;;;;;;;;;AAUA,eAAsB,WACpB,SACA,OACiB;CACjB,MAAM,SAAS,MAAM,eAAe,SAAS,KAAK;CAClD,IAAI,CAAC,QAAQ;EACX,MAAM,UAAU,eAAe,KAAK;EACpC,MAAM,OAAO,YAAY,SAAS,KAAK;EAEvC,MAAM,IAAI,MACR,OAAO,QAAQ,qBACb,KACD,+OACH;CACF;CAEA,OAAO;AACT"}