@northern/yaml-loader 1.0.0 → 1.0.3

package/lib/index.d.ts

@@ -0,0 +1,53 @@
+export interface YamlNode {
+    $ref?: string;
+    [key: string]: YamlNode | YamlNode[] | string | number | boolean | null | undefined;
+}
+export interface RefResolution {
+    filePath: string;
+    pointer: string;
+    resolved: any;
+}
+export interface YamlLoaderOptions {
+    maxCacheSize?: number;
+    allowExternalAccess?: boolean;
+    customResolvers?: Map<string, (ref: string) => any>;
+    strictMode?: boolean;
+}
+export interface DebugInfo {
+    refChain: string[];
+    fileCache: Map<string, string>;
+    resolutionTime: number;
+}
+export interface ValidationResult {
+    isValid: boolean;
+    errors: YamlLoaderError[];
+    warnings: string[];
+}
+export declare class YamlLoaderError extends Error {
+    readonly type: 'circular_ref' | 'file_not_found' | 'invalid_pointer' | 'parse_error';
+    readonly path?: string | undefined;
+    readonly refChain?: string[] | undefined;
+    constructor(message: string, type: 'circular_ref' | 'file_not_found' | 'invalid_pointer' | 'parse_error', path?: string | undefined, refChain?: string[] | undefined);
+}
+export declare function loadYaml<T = any>(filename: string, options?: YamlLoaderOptions): T;
+export declare function loadYamlWithDebug<T = any>(filename: string, options?: YamlLoaderOptions): {
+    result: T;
+    debug: DebugInfo;
+};
+export declare function validateYamlReferences(filename: string, options?: YamlLoaderOptions): ValidationResult;
+export declare class YamlLoaderBuilder {
+    private options;
+    withCache(size: number): this;
+    withStrictMode(enabled: boolean): this;
+    withExternalAccess(enabled: boolean): this;
+    withCustomResolver(prefix: string, resolver: (ref: string) => any): this;
+    build(): (filename: string) => any;
+    buildGeneric<T = any>(): (filename: string) => T;
+}
+export declare function getTestCacheInterface(filename: string, options?: YamlLoaderOptions): {
+    clear: () => void;
+    size: () => number;
+    has: (key: string) => boolean;
+    getCache: () => Map<string, any>;
+};
+export default loadYaml;

package/lib/index.js

@@ -0,0 +1,272 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YamlLoaderBuilder = exports.YamlLoaderError = void 0;
+exports.loadYaml = loadYaml;
+exports.loadYamlWithDebug = loadYamlWithDebug;
+exports.validateYamlReferences = validateYamlReferences;
+exports.getTestCacheInterface = getTestCacheInterface;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const yaml_1 = require("yaml");
+class YamlLoaderError extends Error {
+    constructor(message, type, path, refChain) {
+        super(message);
+        this.type = type;
+        this.path = path;
+        this.refChain = refChain;
+        this.name = 'YamlLoaderError';
+    }
+}
+exports.YamlLoaderError = YamlLoaderError;
+class LRUFileCache {
+    constructor(maxSize = 100) {
+        this.cache = new Map();
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const value = this.cache.get(key);
+        if (value !== undefined) {
+            this.cache.delete(key);
+            this.cache.set(key, value);
+        }
+        return value;
+    }
+    set(key, value) {
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined) {
+                this.cache.delete(firstKey);
+            }
+        }
+        this.cache.set(key, value);
+    }
+    has(key) {
+        return this.cache.has(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    size() {
+        return this.cache.size;
+    }
+    getCache() {
+        return this.cache;
+    }
+}
+const loadFile = (filename) => {
+    const content = (0, fs_1.readFileSync)(filename, 'utf-8');
+    const ext = (0, path_1.extname)(filename).toLowerCase();
+    if (ext === '.json') {
+        return JSON.parse(content);
+    }
+    return (0, yaml_1.parse)(content);
+};
+const resolvePointer = (obj, pointer) => {
+    if (!pointer || pointer === '' || pointer === '/') {
+        return obj;
+    }
+    const parts = pointer.split('/').filter(Boolean);
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== 'object') {
+            throw new YamlLoaderError(`Cannot resolve pointer "${pointer}": path not found`, 'invalid_pointer', pointer);
+        }
+        const decoded = part.replace(/~1/g, '/').replace(/~0/g, '~');
+        current = current[decoded];
+    }
+    return current;
+};
+const resolvePath = (baseDir, filePath, options) => {
+    const resolved = (0, path_1.resolve)(baseDir, filePath);
+    if (!options.allowExternalAccess && !resolved.startsWith(baseDir)) {
+        throw new YamlLoaderError(`Attempted to access file outside base directory: ${filePath}`, 'invalid_pointer', resolved);
+    }
+    return resolved;
+};
+const parseRef = (ref) => {
+    const [filePath, pointer = ''] = ref.split('#');
+    return { filePath, pointer };
+};
+const resolveRefs = (obj, baseDir, context, rootDoc) => {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(item => resolveRefs(item, baseDir, context, rootDoc));
+    }
+    if (typeof obj !== 'object') {
+        return obj;
+    }
+    if (obj.$ref && typeof obj.$ref === 'string' && context.options.customResolvers) {
+        for (const [prefix, resolver] of context.options.customResolvers) {
+            if (obj.$ref.startsWith(prefix)) {
+                return resolver(obj.$ref);
+            }
+        }
+    }
+    if (obj.$ref && typeof obj.$ref === 'string') {
+        const { filePath, pointer } = parseRef(obj.$ref);
+        if (filePath) {
+            const resolvedPath = resolvePath(baseDir, filePath, context.options);
+            const refKey = resolvedPath + '#' + pointer;
+            if (context.pathSet.has(refKey)) {
+                throw new YamlLoaderError(`Circular reference detected: ${context.pathChain.join(' -> ')} -> ${refKey}`, 'circular_ref', refKey, [...context.pathChain, refKey]);
+            }
+            context.pathChain.push(refKey);
+            context.pathSet.add(refKey);
+            try {
+                let refContent;
+                if (context.fileCache.has(resolvedPath)) {
+                    refContent = context.fileCache.get(resolvedPath);
+                }
+                else {
+                    try {
+                        refContent = loadFile(resolvedPath);
+                        context.fileCache.set(resolvedPath, refContent);
+                    }
+                    catch (error) {
+                        throw new YamlLoaderError(`Failed to load file: ${resolvedPath}`, 'file_not_found', resolvedPath, context.pathChain);
+                    }
+                }
+                const refBaseDir = (0, path_1.dirname)(resolvedPath);
+                const resolved = resolvePointer(refContent, pointer);
+                return resolveRefs(resolved, refBaseDir, context, refContent);
+            }
+            finally {
+                context.pathChain.pop();
+                context.pathSet.delete(refKey);
+            }
+        }
+        else {
+            if (!rootDoc) {
+                throw new YamlLoaderError(`Cannot resolve internal reference "${obj.$ref}": root document not available`, 'invalid_pointer', obj.$ref, context.pathChain);
+            }
+            const refKey = '#' + pointer;
+            if (context.pathSet.has(refKey)) {
+                throw new YamlLoaderError(`Circular reference detected: ${context.pathChain.join(' -> ')} -> ${refKey}`, 'circular_ref', refKey, [...context.pathChain, refKey]);
+            }
+            context.pathChain.push(refKey);
+            context.pathSet.add(refKey);
+            try {
+                const resolved = resolvePointer(rootDoc, pointer);
+                return resolveRefs(resolved, baseDir, context, rootDoc);
+            }
+            finally {
+                context.pathChain.pop();
+                context.pathSet.delete(refKey);
+            }
+        }
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        result[key] = resolveRefs(value, baseDir, context, rootDoc);
+    }
+    return result;
+};
+const createResolutionContext = (options = {}) => {
+    return {
+        pathChain: [],
+        pathSet: new Set(),
+        fileCache: new LRUFileCache(options.maxCacheSize || 100),
+        options: Object.assign({ maxCacheSize: 100, allowExternalAccess: false, strictMode: false, customResolvers: new Map() }, options),
+        startTime: Date.now(),
+    };
+};
+function loadYaml(filename, options) {
+    const context = createResolutionContext(options);
+    try {
+        const content = loadFile(filename);
+        const baseDir = (0, path_1.dirname)(filename);
+        return resolveRefs(content, baseDir, context, content);
+    }
+    catch (error) {
+        if (error instanceof YamlLoaderError) {
+            throw error;
+        }
+        throw new YamlLoaderError(`Failed to parse YAML file: ${error instanceof Error ? error.message : String(error)}`, 'parse_error', filename);
+    }
+}
+function loadYamlWithDebug(filename, options) {
+    const context = createResolutionContext(options);
+    try {
+        const content = loadFile(filename);
+        const baseDir = (0, path_1.dirname)(filename);
+        const result = resolveRefs(content, baseDir, context, content);
+        return {
+            result,
+            debug: {
+                refChain: [...context.pathChain],
+                fileCache: new Map(Array.from(context.fileCache.getCache().entries()).map(([k, v]) => [k, typeof v])),
+                resolutionTime: Date.now() - context.startTime,
+            },
+        };
+    }
+    catch (error) {
+        if (error instanceof YamlLoaderError) {
+            throw error;
+        }
+        throw new YamlLoaderError(`Failed to parse YAML file: ${error instanceof Error ? error.message : String(error)}`, 'parse_error', filename);
+    }
+}
+function validateYamlReferences(filename, options) {
+    const errors = [];
+    const warnings = [];
+    try {
+        const context = createResolutionContext(options);
+        const content = loadFile(filename);
+        const baseDir = (0, path_1.dirname)(filename);
+        resolveRefs(content, baseDir, context, content);
+        return { isValid: true, errors, warnings };
+    }
+    catch (error) {
+        if (error instanceof YamlLoaderError) {
+            errors.push(error);
+        }
+        else {
+            errors.push(new YamlLoaderError(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`, 'parse_error', filename));
+        }
+        return { isValid: false, errors, warnings };
+    }
+}
+class YamlLoaderBuilder {
+    constructor() {
+        this.options = {};
+    }
+    withCache(size) {
+        this.options.maxCacheSize = size;
+        return this;
+    }
+    withStrictMode(enabled) {
+        this.options.strictMode = enabled;
+        return this;
+    }
+    withExternalAccess(enabled) {
+        this.options.allowExternalAccess = enabled;
+        return this;
+    }
+    withCustomResolver(prefix, resolver) {
+        if (!this.options.customResolvers) {
+            this.options.customResolvers = new Map();
+        }
+        this.options.customResolvers.set(prefix, resolver);
+        return this;
+    }
+    build() {
+        return (filename) => loadYaml(filename, this.options);
+    }
+    buildGeneric() {
+        return (filename) => loadYaml(filename, this.options);
+    }
+}
+exports.YamlLoaderBuilder = YamlLoaderBuilder;
+function getTestCacheInterface(filename, options) {
+    const context = createResolutionContext(options);
+    loadFile(filename);
+    return {
+        clear: () => context.fileCache.clear(),
+        size: () => context.fileCache.size(),
+        has: (key) => context.fileCache.has(key),
+        getCache: () => context.fileCache.getCache(),
+    };
+}
+exports.default = loadYaml;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@northern/yaml-loader",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "Load YAML files from fragment sources",
   "main": "lib/index.js",
   "files": [
@@ -19,9 +19,9 @@
     "url": "git+https://github.com/northern/yaml-loader.git"
   },
   "keywords": [
-    "di",
-    "dependency injection",
-    "inversion of control",
+    "yaml",
+    "loading",
+    "openapi",
     "library"
   ],
   "publishConfig": {