@kravc/schema 2.8.0-alpha.0 → 2.8.0-alpha.2

package/dist/helpers/createSchemasMap.d.ts

@@ -0,0 +1,98 @@
+import Schema from '../Schema';
+/**
+ * Reads schema source from YAML file and returns a Schema instance.
+ *
+ * **Intent:** Load and parse a single YAML schema file, extracting the schema ID
+ * from the filename and creating a Schema instance for use in validation or
+ * schema composition.
+ *
+ * **Use Cases:**
+ * - Load individual schema files during application startup
+ * - Parse YAML schema definitions into Schema instances
+ * - Extract schema identifiers from file paths automatically
+ * - Support both enum and properties-based schemas from YAML files
+ *
+ * @param yamlPath - Absolute or relative path to the YAML schema file
+ * @returns A Schema instance with ID extracted from the filename (without .yaml extension)
+ *
+ * **Example:**
+ * ```typescript
+ * const schema = loadSync('/path/to/schemas/User.yaml');
+ * // schema.id === 'User'
+ * // schema.source contains the parsed YAML content
+ * ```
+ *
+ * **Example - Enum Schema:**
+ * ```typescript
+ * const statusSchema = loadSync('/path/to/schemas/Status.yaml');
+ * // If Status.yaml contains: { enum: ['PENDING', 'ACTIVE'] }
+ * // statusSchema.isEnum === true
+ * ```
+ */
+export declare const loadSync: (yamlPath: string) => Schema;
+/**
+ * Creates a map of schemas by ID, loading from YAML files and merging with programmatic schemas.
+ *
+ * **Intent:** Build a centralized schema registry that combines file-based YAML schemas
+ * with programmatically created Schema instances, providing a unified lookup mechanism
+ * by schema ID. This enables hybrid schema management where some schemas are defined
+ * in YAML files while others are created dynamically in code.
+ *
+ * **Use Cases:**
+ * - Initialize schema registries for validators from both files and code
+ * - Support schema composition where base schemas come from files and extended
+ *   schemas are created programmatically
+ * - Enable schema overriding where programmatic schemas can replace file-based ones
+ * - Build schema maps for credential factories or API validation systems
+ * - Support development workflows where schemas evolve from YAML to code
+ *
+ * @param servicePath - Path to directory containing YAML schema files (searched recursively)
+ * @param modules - Array of Schema instances or other values (non-Schema values are filtered out)
+ * @returns Record mapping schema IDs to Schema instances, with modules schemas overriding YAML schemas
+ *
+ * **Example - Basic Usage:**
+ * ```typescript
+ * const schemasMap = createSchemasMap('/path/to/examples/schemas', []);
+ * // Returns: {
+ * //   FavoriteItem: Schema { id: 'FavoriteItem', ... },
+ * //   Profile: Schema { id: 'Profile', ... },
+ * //   Status: Schema { id: 'Status', ... },
+ * //   Preferences: Schema { id: 'Preferences', ... }
+ * // }
+ * ```
+ *
+ * **Example - Merging Programmatic Schemas:**
+ * ```typescript
+ * const customSchema = new Schema(
+ *   { customField: { type: 'string' } },
+ *   'CustomSchema'
+ * );
+ * const schemasMap = createSchemasMap('/path/to/schemas', [customSchema]);
+ * // schemasMap contains both YAML schemas and CustomSchema
+ * ```
+ *
+ * **Example - Overriding YAML Schemas:**
+ * ```typescript
+ * const updatedProfile = new Schema(
+ *   { name: { type: 'string' }, newField: { type: 'number' } },
+ *   'Profile'
+ * );
+ * const schemasMap = createSchemasMap('/path/to/schemas', [updatedProfile]);
+ * // schemasMap.Profile is the updatedProfile instance, not the YAML version
+ * ```
+ *
+ * **Example - Filtering Non-Schema Values:**
+ * ```typescript
+ * const schema = new Schema({ field: { type: 'string' } }, 'Test');
+ * const schemasMap = createSchemasMap('/path/to/schemas', [
+ *   schema,
+ *   'not a schema',
+ *   { id: 'fake' },
+ *   null
+ * ]);
+ * // Only the Schema instance is included, other values are ignored
+ * ```
+ */
+declare const createSchemasMap: (servicePath: string, modules: unknown[]) => Record<string, Schema>;
+export default createSchemasMap;
+//# sourceMappingURL=createSchemasMap.d.ts.map

package/dist/helpers/createSchemasMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createSchemasMap.d.ts","sourceRoot":"","sources":["../../src/helpers/createSchemasMap.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,WAAW,CAAC;AAM/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,QAAQ,GAAI,UAAU,MAAM,WAUxC,CAAC;AAuFF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,QAAA,MAAM,gBAAgB,GAAI,aAAa,MAAM,EAAE,SAAS,OAAO,EAAE,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAYxF,CAAC;AAEF,eAAe,gBAAgB,CAAC"}

package/dist/helpers/createSchemasMap.js

@@ -0,0 +1,202 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSync = void 0;
+const path_1 = __importDefault(require("path"));
+const Schema_1 = __importDefault(require("../Schema"));
+const js_yaml_1 = require("js-yaml");
+const lodash_1 = require("lodash");
+const fs_1 = require("fs");
+/**
+ * Reads schema source from YAML file and returns a Schema instance.
+ *
+ * **Intent:** Load and parse a single YAML schema file, extracting the schema ID
+ * from the filename and creating a Schema instance for use in validation or
+ * schema composition.
+ *
+ * **Use Cases:**
+ * - Load individual schema files during application startup
+ * - Parse YAML schema definitions into Schema instances
+ * - Extract schema identifiers from file paths automatically
+ * - Support both enum and properties-based schemas from YAML files
+ *
+ * @param yamlPath - Absolute or relative path to the YAML schema file
+ * @returns A Schema instance with ID extracted from the filename (without .yaml extension)
+ *
+ * **Example:**
+ * ```typescript
+ * const schema = loadSync('/path/to/schemas/User.yaml');
+ * // schema.id === 'User'
+ * // schema.source contains the parsed YAML content
+ * ```
+ *
+ * **Example - Enum Schema:**
+ * ```typescript
+ * const statusSchema = loadSync('/path/to/schemas/Status.yaml');
+ * // If Status.yaml contains: { enum: ['PENDING', 'ACTIVE'] }
+ * // statusSchema.isEnum === true
+ * ```
+ */
+const loadSync = (yamlPath) => {
+    const schemaId = yamlPath
+        .split('/')
+        .reverse()[0]
+        .split('.yaml')[0];
+    const file = (0, fs_1.readFileSync)(yamlPath);
+    const source = (0, js_yaml_1.load)(file.toString());
+    return new Schema_1.default(source, schemaId);
+};
+exports.loadSync = loadSync;
+/**
+ * Recursively lists all files in a directory and its subdirectories.
+ *
+ * **Intent:** Traverse a directory tree and collect all file paths, enabling
+ * discovery of schema files nested in subdirectories without manual path specification.
+ *
+ * **Use Cases:**
+ * - Find all schema files in a directory structure
+ * - Support organized schema layouts with nested folders
+ * - Enable schema discovery without hardcoding file paths
+ * - Prepare file list for filtering and processing
+ *
+ * @param servicePath - Path to the directory to traverse
+ * @returns Array of absolute file paths found in the directory tree
+ *
+ * **Example:**
+ * ```typescript
+ * const files = listFilesSync('/path/to/schemas');
+ * // Returns: [
+ * //   '/path/to/schemas/User.yaml',
+ * //   '/path/to/schemas/nested/Profile.yaml',
+ * //   '/path/to/schemas/nested/deep/Status.yaml'
+ * // ]
+ * ```
+ *
+ * **Example - Flat Directory:**
+ * ```typescript
+ * const files = listFilesSync('/path/to/schemas');
+ * // Returns: [
+ * //   '/path/to/schemas/User.yaml',
+ * //   '/path/to/schemas/Profile.yaml'
+ * // ]
+ * ```
+ */
+const listFilesSync = (servicePath) => (0, fs_1.readdirSync)(servicePath)
+    .reduce((filePaths, fileName) => (0, fs_1.statSync)(path_1.default.join(servicePath, fileName)).isDirectory() ?
+    filePaths.concat(listFilesSync(path_1.default.join(servicePath, fileName))) :
+    filePaths.concat(path_1.default.join(servicePath, fileName)), []);
+/**
+ * Reads all YAML schema files from a directory and creates Schema instances.
+ *
+ * **Intent:** Bulk load schema definitions from YAML files in a directory,
+ * automatically discovering and parsing all schema files for use in schema
+ * registries or validators.
+ *
+ * **Use Cases:**
+ * - Load all schemas from a schemas directory at application startup
+ * - Initialize schema registries from file-based definitions
+ * - Support schema-as-code workflows where schemas are stored as YAML files
+ * - Enable automatic schema discovery without manual registration
+ *
+ * @param servicePath - Path to the directory containing YAML schema files
+ * @returns Array of Schema instances, one for each YAML file found
+ *
+ * **Example:**
+ * ```typescript
+ * const schemas = readSchemasSync('/path/to/examples/schemas');
+ * // Returns: [
+ * //   Schema { id: 'FavoriteItem', ... },
+ * //   Schema { id: 'Profile', ... },
+ * //   Schema { id: 'Status', ... },
+ * //   Schema { id: 'Preferences', ... }
+ * // ]
+ * ```
+ *
+ * **Example - With Nested Directories:**
+ * ```typescript
+ * const schemas = readSchemasSync('/path/to/schemas');
+ * // Automatically finds schemas in subdirectories:
+ * // - /path/to/schemas/User.yaml
+ * // - /path/to/schemas/nested/Profile.yaml
+ * ```
+ */
+const readSchemasSync = (servicePath) => listFilesSync(servicePath)
+    .filter((fileName) => fileName.endsWith('.yaml'))
+    .map((schemaPath) => (0, exports.loadSync)(schemaPath));
+/**
+ * Creates a map of schemas by ID, loading from YAML files and merging with programmatic schemas.
+ *
+ * **Intent:** Build a centralized schema registry that combines file-based YAML schemas
+ * with programmatically created Schema instances, providing a unified lookup mechanism
+ * by schema ID. This enables hybrid schema management where some schemas are defined
+ * in YAML files while others are created dynamically in code.
+ *
+ * **Use Cases:**
+ * - Initialize schema registries for validators from both files and code
+ * - Support schema composition where base schemas come from files and extended
+ *   schemas are created programmatically
+ * - Enable schema overriding where programmatic schemas can replace file-based ones
+ * - Build schema maps for credential factories or API validation systems
+ * - Support development workflows where schemas evolve from YAML to code
+ *
+ * @param servicePath - Path to directory containing YAML schema files (searched recursively)
+ * @param modules - Array of Schema instances or other values (non-Schema values are filtered out)
+ * @returns Record mapping schema IDs to Schema instances, with modules schemas overriding YAML schemas
+ *
+ * **Example - Basic Usage:**
+ * ```typescript
+ * const schemasMap = createSchemasMap('/path/to/examples/schemas', []);
+ * // Returns: {
+ * //   FavoriteItem: Schema { id: 'FavoriteItem', ... },
+ * //   Profile: Schema { id: 'Profile', ... },
+ * //   Status: Schema { id: 'Status', ... },
+ * //   Preferences: Schema { id: 'Preferences', ... }
+ * // }
+ * ```
+ *
+ * **Example - Merging Programmatic Schemas:**
+ * ```typescript
+ * const customSchema = new Schema(
+ *   { customField: { type: 'string' } },
+ *   'CustomSchema'
+ * );
+ * const schemasMap = createSchemasMap('/path/to/schemas', [customSchema]);
+ * // schemasMap contains both YAML schemas and CustomSchema
+ * ```
+ *
+ * **Example - Overriding YAML Schemas:**
+ * ```typescript
+ * const updatedProfile = new Schema(
+ *   { name: { type: 'string' }, newField: { type: 'number' } },
+ *   'Profile'
+ * );
+ * const schemasMap = createSchemasMap('/path/to/schemas', [updatedProfile]);
+ * // schemasMap.Profile is the updatedProfile instance, not the YAML version
+ * ```
+ *
+ * **Example - Filtering Non-Schema Values:**
+ * ```typescript
+ * const schema = new Schema({ field: { type: 'string' } }, 'Test');
+ * const schemasMap = createSchemasMap('/path/to/schemas', [
+ *   schema,
+ *   'not a schema',
+ *   { id: 'fake' },
+ *   null
+ * ]);
+ * // Only the Schema instance is included, other values are ignored
+ * ```
+ */
+const createSchemasMap = (servicePath, modules) => {
+    const yamlSchemas = readSchemasSync(servicePath);
+    const schemasMap = (0, lodash_1.keyBy)(yamlSchemas, 'id');
+    const schemas = modules
+        .filter(schema => schema instanceof Schema_1.default);
+    for (const schema of schemas) {
+        schemasMap[schema.id] = schema;
+    }
+    return schemasMap;
+};
+exports.default = createSchemasMap;
+//# sourceMappingURL=createSchemasMap.js.map

package/dist/helpers/createSchemasMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createSchemasMap.js","sourceRoot":"","sources":["../../src/helpers/createSchemasMap.ts"],"names":[],"mappings":";;;;;;AAAA,gDAAwB;AACxB,uDAA+B;AAC/B,qCAA+B;AAC/B,mCAA+B;AAE/B,2BAAyD;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACI,MAAM,QAAQ,GAAG,CAAC,QAAgB,EAAE,EAAE;IAC3C,MAAM,QAAQ,GAAG,QAAQ;SACtB,KAAK,CAAC,GAAG,CAAC;SACV,OAAO,EAAE,CAAC,CAAC,CAAC;SACZ,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAErB,MAAM,IAAI,GAAG,IAAA,iBAAY,EAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,MAAM,GAAG,IAAA,cAAI,EAAC,IAAI,CAAC,QAAQ,EAAE,CAAkC,CAAC;IAEtE,OAAO,IAAI,gBAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AACtC,CAAC,CAAC;AAVW,QAAA,QAAQ,YAUnB;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,aAAa,GAAG,CAAC,WAAmB,EAAY,EAAE,CACtD,IAAA,gBAAW,EAAC,WAAW,CAAC;KACrB,MAAM,CACL,CAAC,SAAmB,EAAE,QAAgB,EAAE,EAAE,CACxC,IAAA,aAAQ,EACN,cAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IAC/C,SAAS,CAAC,MAAM,CAAC,aAAa,CAAC,cAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,SAAS,CAAC,MAAM,CAAC,cAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CACpD,EACH,EAAE,CAAC,CAAC;AAEV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,eAAe,GAAG,CAAC,WAAmB,EAAE,EAAE,CAC9C,aAAa,CAAC,WAAW,CAAC;KACvB,MAAM,CAAC,CAAC,QAAgB,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;KACxD,GAAG,CAAC,CAAC,UAAkB,EAAE,EAAE,CAAC,IAAA,gBAAQ,EAAC,UAAU,CAAC,CAAC,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,MAAM,gBAAgB,GAAG,CAAC,WAAmB,EAAE,OAAkB,EAA0B,EAAE;IAC3F,MAAM,WAAW,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;IACjD,MAAM,UAAU,GAAG,IAAA,cAAK,EAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IAE5C,MAAM,OAAO,GAAG,OAAO;SACpB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,YAAY,gBAAM,CAAC,CAAC;IAE9C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC;IACjC,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC,CAAC;AAEF,kBAAe,gBAAgB,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,9 @@
+import got from './helpers/got';
 import Schema from './Schema';
 import Validator from './Validator';
 import documentLoader from './ld/documentLoader';
 import ValidationError from './ValidationError';
 import CredentialFactory from './CredentialFactory';
-export { Schema, Validator, documentLoader, ValidationError, CredentialFactory };
+import createSchemasMap, { loadSync } from './helpers/createSchemasMap';
+export { got, Schema, loadSync, Validator, documentLoader, ValidationError, createSchemasMap, CredentialFactory };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,UAAU,CAAC;AAC9B,OAAO,SAAS,MAAM,aAAa,CAAC;AACpC,OAAO,cAAc,MAAM,qBAAqB,CAAC;AACjD,OAAO,eAAe,MAAM,mBAAmB,CAAC;AAChD,OAAO,iBAAiB,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EACL,MAAM,EACN,SAAS,EACT,cAAc,EACd,eAAe,EACf,iBAAiB,EAClB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,eAAe,CAAC;AAChC,OAAO,MAAM,MAAM,UAAU,CAAC;AAC9B,OAAO,SAAS,MAAM,aAAa,CAAC;AACpC,OAAO,cAAc,MAAM,qBAAqB,CAAC;AACjD,OAAO,eAAe,MAAM,mBAAmB,CAAC;AAChD,OAAO,iBAAiB,MAAM,qBAAqB,CAAC;AACpD,OAAO,gBAAgB,EAAE,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAExE,OAAO,EACL,GAAG,EACH,MAAM,EACN,QAAQ,EACR,SAAS,EACT,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EAClB,CAAC"}

package/dist/index.js

@@ -1,9 +1,44 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CredentialFactory = exports.ValidationError = exports.documentLoader = exports.Validator = exports.Schema = void 0;
+exports.CredentialFactory = exports.createSchemasMap = exports.ValidationError = exports.documentLoader = exports.Validator = exports.loadSync = exports.Schema = exports.got = void 0;
+const got_1 = __importDefault(require("./helpers/got"));
+exports.got = got_1.default;
 const Schema_1 = __importDefault(require("./Schema"));
 exports.Schema = Schema_1.default;
 const Validator_1 = __importDefault(require("./Validator"));
@@ -14,4 +49,7 @@ const ValidationError_1 = __importDefault(require("./ValidationError"));
 exports.ValidationError = ValidationError_1.default;
 const CredentialFactory_1 = __importDefault(require("./CredentialFactory"));
 exports.CredentialFactory = CredentialFactory_1.default;
+const createSchemasMap_1 = __importStar(require("./helpers/createSchemasMap"));
+exports.createSchemasMap = createSchemasMap_1.default;
+Object.defineProperty(exports, "loadSync", { enumerable: true, get: function () { return createSchemasMap_1.loadSync; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAAA,sDAA8B;AAO5B,iBAPK,gBAAM,CAOL;AANR,4DAAoC;AAOlC,oBAPK,mBAAS,CAOL;AANX,yEAAiD;AAO/C,yBAPK,wBAAc,CAOL;AANhB,wEAAgD;AAO9C,0BAPK,yBAAe,CAOL;AANjB,4EAAoD;AAOlD,4BAPK,2BAAiB,CAOL"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,wDAAgC;AAS9B,cATK,aAAG,CASL;AARL,sDAA8B;AAS5B,iBATK,gBAAM,CASL;AARR,4DAAoC;AAUlC,oBAVK,mBAAS,CAUL;AATX,yEAAiD;AAU/C,yBAVK,wBAAc,CAUL;AAThB,wEAAgD;AAU9C,0BAVK,yBAAe,CAUL;AATjB,4EAAoD;AAWlD,4BAXK,2BAAiB,CAWL;AAVnB,+EAAwE;AAStE,2BATK,0BAAgB,CASL;AAJhB,yFALyB,2BAAQ,OAKzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kravc/schema",
-  "version": "2.8.0-alpha.0",
+  "version": "2.8.0-alpha.2",
   "description": "Advanced JSON schema manipulation and validation library.",
   "keywords": [
     "JSON",

package/src/helpers/__tests__/createSchemasMap.test.ts

@@ -0,0 +1,238 @@
+import path from 'path';
+import createSchemasMap from '../createSchemasMap';
+import Schema from '../../Schema';
+
+describe('createSchemasMap', () => {
+  const examplesSchemasPath = path.join(__dirname, '../../../examples/schemas');
+
+  describe('loading schemas from YAML files', () => {
+    it('should load all YAML schemas from the examples/schemas directory', () => {
+      const schemasMap = createSchemasMap(examplesSchemasPath, []);
+
+      expect(Object.keys(schemasMap).length).toBeGreaterThan(0);
+      expect(schemasMap).toHaveProperty('FavoriteItem');
+      expect(schemasMap).toHaveProperty('Profile');
+      expect(schemasMap).toHaveProperty('Status');
+      expect(schemasMap).toHaveProperty('Preferences');
+    });
+
+    it('should create Schema instances from YAML files', () => {
+      const schemasMap = createSchemasMap(examplesSchemasPath, []);
+
+      expect(schemasMap.FavoriteItem).toBeInstanceOf(Schema);
+      expect(schemasMap.Profile).toBeInstanceOf(Schema);
+      expect(schemasMap.Status).toBeInstanceOf(Schema);
+      expect(schemasMap.Preferences).toBeInstanceOf(Schema);
+    });
+
+    it('should extract schema ID from YAML filename', () => {
+      const schemasMap = createSchemasMap(examplesSchemasPath, []);
+
+      expect(schemasMap.FavoriteItem.id).toBe('FavoriteItem');
+      expect(schemasMap.Profile.id).toBe('Profile');
+      expect(schemasMap.Status.id).toBe('Status');
+      expect(schemasMap.Preferences.id).toBe('Preferences');
+    });
+
+    it('should handle enum schemas correctly', () => {
+      const schemasMap = createSchemasMap(examplesSchemasPath, []);
+
+      expect(schemasMap.Status).toBeInstanceOf(Schema);
+      expect(schemasMap.Status.isEnum).toBe(true);
+    });
+
+    it('should handle properties schemas correctly', () => {
+      const schemasMap = createSchemasMap(examplesSchemasPath, []);
+
+      expect(schemasMap.Profile).toBeInstanceOf(Schema);
+      expect(schemasMap.Profile.isEnum).toBe(false);
+      expect(schemasMap.FavoriteItem).toBeInstanceOf(Schema);
+      expect(schemasMap.FavoriteItem.isEnum).toBe(false);
+    });
+  });
+
+  describe('merging modules array', () => {
+    it('should merge Schema instances from modules array', () => {
+      const customSchema = new Schema(
+        { customField: { type: 'string' } },
+        'CustomSchema'
+      );
+
+      const schemasMap = createSchemasMap(examplesSchemasPath, [customSchema]);
+
+      expect(schemasMap.CustomSchema).toBeInstanceOf(Schema);
+      expect(schemasMap.CustomSchema.id).toBe('CustomSchema');
+    });
+
+    it('should override YAML schemas with modules schemas if same ID', () => {
+      const customProfile = new Schema(
+        { customField: { type: 'string' } },
+        'Profile'
+      );
+
+      const schemasMap = createSchemasMap(examplesSchemasPath, [customProfile]);
+
+      expect(schemasMap.Profile).toBeInstanceOf(Schema);
+      expect(schemasMap.Profile.id).toBe('Profile');
+      // The custom schema should override the YAML one
+      const source = schemasMap.Profile.source;
+      expect(source).toHaveProperty('customField');
+    });
+
+    it('should filter out non-Schema instances from modules', () => {
+      const customSchema = new Schema(
+        { customField: { type: 'string' } },
+        'CustomSchema'
+      );
+      const notASchema = { id: 'NotASchema', someProperty: 'value' };
+      const alsoNotASchema = 'string value';
+
+      const schemasMap = createSchemasMap(examplesSchemasPath, [
+        customSchema,
+        notASchema,
+        alsoNotASchema,
+        null,
+        undefined,
+      ]);
+
+      expect(schemasMap.CustomSchema).toBeInstanceOf(Schema);
+      expect(schemasMap).not.toHaveProperty('NotASchema');
+    });
+
+    it('should handle empty modules array', () => {
+      const schemasMap = createSchemasMap(examplesSchemasPath, []);
+
+      expect(Object.keys(schemasMap).length).toBeGreaterThan(0);
+      expect(schemasMap.FavoriteItem).toBeInstanceOf(Schema);
+    });
+
+    it('should merge multiple Schema instances from modules', () => {
+      const schema1 = new Schema({ field1: { type: 'string' } }, 'Schema1');
+      const schema2 = new Schema({ field2: { type: 'number' } }, 'Schema2');
+      const schema3 = new Schema({ field3: { type: 'boolean' } }, 'Schema3');
+
+      const schemasMap = createSchemasMap(examplesSchemasPath, [
+        schema1,
+        schema2,
+        schema3,
+      ]);
+
+      expect(schemasMap.Schema1).toBeInstanceOf(Schema);
+      expect(schemasMap.Schema2).toBeInstanceOf(Schema);
+      expect(schemasMap.Schema3).toBeInstanceOf(Schema);
+      expect(schemasMap.Schema1.id).toBe('Schema1');
+      expect(schemasMap.Schema2.id).toBe('Schema2');
+      expect(schemasMap.Schema3.id).toBe('Schema3');
+    });
+  });
+
+  describe('return value structure', () => {
+    it('should return a Record<string, Schema>', () => {
+      const schemasMap = createSchemasMap(examplesSchemasPath, []);
+
+      expect(typeof schemasMap).toBe('object');
+      expect(schemasMap).not.toBeNull();
+      expect(Array.isArray(schemasMap)).toBe(false);
+
+      // Check that all values are Schema instances
+      Object.values(schemasMap).forEach((schema) => {
+        expect(schema).toBeInstanceOf(Schema);
+      });
+    });
+
+    it('should use schema ID as keys in the map', () => {
+      const schemasMap = createSchemasMap(examplesSchemasPath, []);
+
+      Object.entries(schemasMap).forEach(([key, schema]) => {
+        expect(schema.id).toBe(key);
+      });
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty directory gracefully', () => {
+      const emptyDir = path.join(__dirname, '../../../examples');
+      // This directory might have subdirectories but no YAML files directly
+      // We'll test with a path that exists but may have no YAML files
+      const schemasMap = createSchemasMap(emptyDir, []);
+
+      expect(typeof schemasMap).toBe('object');
+      // If there are no YAML files, the map should be empty or contain only what's in modules
+    });
+
+    it('should ignore non-YAML files', () => {
+      const schemasMap = createSchemasMap(examplesSchemasPath, []);
+
+      // Should only contain schemas from YAML files, not TypeScript files
+      Object.keys(schemasMap).forEach((key) => {
+        expect(key).not.toBe('FavoriteItemSchema');
+        expect(key).not.toBe('ProfileSchema');
+        expect(key).not.toBe('PreferencesSchema');
+        expect(key).not.toBe('StatusSchema');
+      });
+    });
+
+    it('should handle modules array with only non-Schema values', () => {
+      const schemasMap = createSchemasMap(examplesSchemasPath, [
+        'string',
+        123,
+        {},
+        null,
+        undefined,
+      ]);
+
+      // Should still have YAML schemas
+      expect(schemasMap.FavoriteItem).toBeInstanceOf(Schema);
+      expect(schemasMap.Profile).toBeInstanceOf(Schema);
+    });
+  });
+
+  describe('schema content validation', () => {
+    it('should correctly parse FavoriteItem schema', () => {
+      const schemasMap = createSchemasMap(examplesSchemasPath, []);
+      const favoriteItem = schemasMap.FavoriteItem;
+
+      expect(favoriteItem).toBeInstanceOf(Schema);
+      expect(favoriteItem.isEnum).toBe(false);
+      const source = favoriteItem.source;
+      expect(source).toHaveProperty('id');
+      expect(source).toHaveProperty('name');
+      expect(source).toHaveProperty('status');
+    });
+
+    it('should correctly parse Profile schema', () => {
+      const schemasMap = createSchemasMap(examplesSchemasPath, []);
+      const profile = schemasMap.Profile;
+
+      expect(profile).toBeInstanceOf(Schema);
+      expect(profile.isEnum).toBe(false);
+      const source = profile.source;
+      expect(source).toHaveProperty('name');
+      expect(source).toHaveProperty('status');
+      expect(source).toHaveProperty('gender');
+    });
+
+    it('should correctly parse Status enum schema', () => {
+      const schemasMap = createSchemasMap(examplesSchemasPath, []);
+      const status = schemasMap.Status;
+
+      expect(status).toBeInstanceOf(Schema);
+      expect(status.isEnum).toBe(true);
+      const source = status.source;
+      expect(source).toHaveProperty('enum');
+      expect(Array.isArray(source.enum)).toBe(true);
+    });
+
+    it('should correctly parse Preferences schema', () => {
+      const schemasMap = createSchemasMap(examplesSchemasPath, []);
+      const preferences = schemasMap.Preferences;
+
+      expect(preferences).toBeInstanceOf(Schema);
+      expect(preferences.isEnum).toBe(false);
+      const source = preferences.source;
+      expect(source).toHaveProperty('age');
+      expect(source).toHaveProperty('height');
+      expect(source).toHaveProperty('isNotificationEnabled');
+    });
+  });
+});

package/src/helpers/createSchemasMap.ts

@@ -0,0 +1,212 @@
+import path from 'path';
+import Schema from '../Schema';
+import { load } from 'js-yaml';
+import { keyBy } from 'lodash';
+import type { EnumSchema, PropertiesSchema } from './JsonSchema';
+import { readFileSync, readdirSync, statSync } from 'fs';
+
+/**
+ * Reads schema source from YAML file and returns a Schema instance.
+ *
+ * **Intent:** Load and parse a single YAML schema file, extracting the schema ID
+ * from the filename and creating a Schema instance for use in validation or
+ * schema composition.
+ *
+ * **Use Cases:**
+ * - Load individual schema files during application startup
+ * - Parse YAML schema definitions into Schema instances
+ * - Extract schema identifiers from file paths automatically
+ * - Support both enum and properties-based schemas from YAML files
+ *
+ * @param yamlPath - Absolute or relative path to the YAML schema file
+ * @returns A Schema instance with ID extracted from the filename (without .yaml extension)
+ *
+ * **Example:**
+ * ```typescript
+ * const schema = loadSync('/path/to/schemas/User.yaml');
+ * // schema.id === 'User'
+ * // schema.source contains the parsed YAML content
+ * ```
+ *
+ * **Example - Enum Schema:**
+ * ```typescript
+ * const statusSchema = loadSync('/path/to/schemas/Status.yaml');
+ * // If Status.yaml contains: { enum: ['PENDING', 'ACTIVE'] }
+ * // statusSchema.isEnum === true
+ * ```
+ */
+export const loadSync = (yamlPath: string) => {
+  const schemaId = yamlPath
+    .split('/')
+    .reverse()[0]
+    .split('.yaml')[0];
+
+  const file = readFileSync(yamlPath);
+  const source = load(file.toString()) as EnumSchema | PropertiesSchema;
+
+  return new Schema(source, schemaId);
+};
+
+/**
+ * Recursively lists all files in a directory and its subdirectories.
+ *
+ * **Intent:** Traverse a directory tree and collect all file paths, enabling
+ * discovery of schema files nested in subdirectories without manual path specification.
+ *
+ * **Use Cases:**
+ * - Find all schema files in a directory structure
+ * - Support organized schema layouts with nested folders
+ * - Enable schema discovery without hardcoding file paths
+ * - Prepare file list for filtering and processing
+ *
+ * @param servicePath - Path to the directory to traverse
+ * @returns Array of absolute file paths found in the directory tree
+ *
+ * **Example:**
+ * ```typescript
+ * const files = listFilesSync('/path/to/schemas');
+ * // Returns: [
+ * //   '/path/to/schemas/User.yaml',
+ * //   '/path/to/schemas/nested/Profile.yaml',
+ * //   '/path/to/schemas/nested/deep/Status.yaml'
+ * // ]
+ * ```
+ *
+ * **Example - Flat Directory:**
+ * ```typescript
+ * const files = listFilesSync('/path/to/schemas');
+ * // Returns: [
+ * //   '/path/to/schemas/User.yaml',
+ * //   '/path/to/schemas/Profile.yaml'
+ * // ]
+ * ```
+ */
+const listFilesSync = (servicePath: string): string[] =>
+  readdirSync(servicePath)
+    .reduce(
+      (filePaths: string[], fileName: string) =>
+        statSync(
+          path.join(servicePath, fileName)).isDirectory() ?
+            filePaths.concat(listFilesSync(path.join(servicePath, fileName))) :
+            filePaths.concat(path.join(servicePath, fileName)
+        )
+    , []);
+
+/**
+ * Reads all YAML schema files from a directory and creates Schema instances.
+ *
+ * **Intent:** Bulk load schema definitions from YAML files in a directory,
+ * automatically discovering and parsing all schema files for use in schema
+ * registries or validators.
+ *
+ * **Use Cases:**
+ * - Load all schemas from a schemas directory at application startup
+ * - Initialize schema registries from file-based definitions
+ * - Support schema-as-code workflows where schemas are stored as YAML files
+ * - Enable automatic schema discovery without manual registration
+ *
+ * @param servicePath - Path to the directory containing YAML schema files
+ * @returns Array of Schema instances, one for each YAML file found
+ *
+ * **Example:**
+ * ```typescript
+ * const schemas = readSchemasSync('/path/to/examples/schemas');
+ * // Returns: [
+ * //   Schema { id: 'FavoriteItem', ... },
+ * //   Schema { id: 'Profile', ... },
+ * //   Schema { id: 'Status', ... },
+ * //   Schema { id: 'Preferences', ... }
+ * // ]
+ * ```
+ *
+ * **Example - With Nested Directories:**
+ * ```typescript
+ * const schemas = readSchemasSync('/path/to/schemas');
+ * // Automatically finds schemas in subdirectories:
+ * // - /path/to/schemas/User.yaml
+ * // - /path/to/schemas/nested/Profile.yaml
+ * ```
+ */
+const readSchemasSync = (servicePath: string) =>
+  listFilesSync(servicePath)
+    .filter((fileName: string) => fileName.endsWith('.yaml'))
+    .map((schemaPath: string) => loadSync(schemaPath));
+
+/**
+ * Creates a map of schemas by ID, loading from YAML files and merging with programmatic schemas.
+ *
+ * **Intent:** Build a centralized schema registry that combines file-based YAML schemas
+ * with programmatically created Schema instances, providing a unified lookup mechanism
+ * by schema ID. This enables hybrid schema management where some schemas are defined
+ * in YAML files while others are created dynamically in code.
+ *
+ * **Use Cases:**
+ * - Initialize schema registries for validators from both files and code
+ * - Support schema composition where base schemas come from files and extended
+ *   schemas are created programmatically
+ * - Enable schema overriding where programmatic schemas can replace file-based ones
+ * - Build schema maps for credential factories or API validation systems
+ * - Support development workflows where schemas evolve from YAML to code
+ *
+ * @param servicePath - Path to directory containing YAML schema files (searched recursively)
+ * @param modules - Array of Schema instances or other values (non-Schema values are filtered out)
+ * @returns Record mapping schema IDs to Schema instances, with modules schemas overriding YAML schemas
+ *
+ * **Example - Basic Usage:**
+ * ```typescript
+ * const schemasMap = createSchemasMap('/path/to/examples/schemas', []);
+ * // Returns: {
+ * //   FavoriteItem: Schema { id: 'FavoriteItem', ... },
+ * //   Profile: Schema { id: 'Profile', ... },
+ * //   Status: Schema { id: 'Status', ... },
+ * //   Preferences: Schema { id: 'Preferences', ... }
+ * // }
+ * ```
+ *
+ * **Example - Merging Programmatic Schemas:**
+ * ```typescript
+ * const customSchema = new Schema(
+ *   { customField: { type: 'string' } },
+ *   'CustomSchema'
+ * );
+ * const schemasMap = createSchemasMap('/path/to/schemas', [customSchema]);
+ * // schemasMap contains both YAML schemas and CustomSchema
+ * ```
+ *
+ * **Example - Overriding YAML Schemas:**
+ * ```typescript
+ * const updatedProfile = new Schema(
+ *   { name: { type: 'string' }, newField: { type: 'number' } },
+ *   'Profile'
+ * );
+ * const schemasMap = createSchemasMap('/path/to/schemas', [updatedProfile]);
+ * // schemasMap.Profile is the updatedProfile instance, not the YAML version
+ * ```
+ *
+ * **Example - Filtering Non-Schema Values:**
+ * ```typescript
+ * const schema = new Schema({ field: { type: 'string' } }, 'Test');
+ * const schemasMap = createSchemasMap('/path/to/schemas', [
+ *   schema,
+ *   'not a schema',
+ *   { id: 'fake' },
+ *   null
+ * ]);
+ * // Only the Schema instance is included, other values are ignored
+ * ```
+ */
+const createSchemasMap = (servicePath: string, modules: unknown[]): Record<string, Schema> => {
+  const yamlSchemas = readSchemasSync(servicePath);
+  const schemasMap = keyBy(yamlSchemas, 'id');
+
+  const schemas = modules
+    .filter(schema => schema instanceof Schema);
+
+  for (const schema of schemas) {
+    schemasMap[schema.id] = schema;
+  }
+
+  return schemasMap;
+};
+
+export default createSchemasMap;

package/src/index.ts

@@ -1,13 +1,18 @@
+import got from './helpers/got';
 import Schema from './Schema';
 import Validator from './Validator';
 import documentLoader from './ld/documentLoader';
 import ValidationError from './ValidationError';
 import CredentialFactory from './CredentialFactory';
+import createSchemasMap, { loadSync } from './helpers/createSchemasMap';
 
 export {
+  got,
   Schema,
+  loadSync,
   Validator,
   documentLoader,
   ValidationError,
+  createSchemasMap,
   CredentialFactory
 };