@axi-engine/configs 0.1.0

package/README.md

@@ -0,0 +1,8 @@
+# @axi-engine/configs
+
+[![NPM version](https://img.shields.io/npm/v/@axi-engine/utils.svg)](https://www.npmjs.com/package/@axi-engine/configs)
+
+
+## Description
+
+Description

package/dist/index.d.mts

@@ -0,0 +1,55 @@
+import { PathType } from '@axi-engine/utils';
+
+/**
+ * Represents a specific configuration variant that can extend another variant.
+ * @template T The base type of the configuration object.
+ */
+type ConfigVariant<T extends object> = {
+    /** Path to a base config (or multiple configs) that this variant extends. */
+    extends?: PathType;
+    /** The specific fields that override or extend the base config. */
+    fields?: Partial<T>;
+};
+/**
+ * Represents the hierarchical structure of the configuration.
+ * It's a recursive type that can contain other trees or final variants.
+ * @template T The base type of the configuration object.
+ */
+type ConfigTree<T extends object> = {
+    [key: string]: ConfigVariant<T> | ConfigTree<T>;
+};
+/**
+ * Type guard to check if an object is a ConfigVariant.
+ */
+declare function isConfigVariant<T extends object>(obj: any): obj is ConfigVariant<T>;
+
+/**
+ * Resolves hierarchical configurations with inheritance and caching.
+ * @template TBase The base type for all configurations this resolver handles.
+ */
+declare class ConfigResolver<TBase extends object> {
+    readonly configs: ConfigTree<TBase>;
+    private cache;
+    constructor(configs: ConfigTree<TBase>);
+    /**
+     * Retrieves a fully resolved and merged configuration for a given path.
+     * @template T A specific subtype of TBase that the caller expects.
+     * @param path Path to the config, e.g., 'enemies.boss.goblin'.
+     * @returns The resolved configuration object.
+     */
+    get<T extends TBase>(path: PathType): T;
+    /**
+     * Clears the cache of resolved configurations.
+     */
+    clearCache(): void;
+    /**
+     * Recursively calculates the configuration by merging a variant with its parents.
+     */
+    private calculateConfig;
+    /**
+     * Traverses the config tree to find the node at the specified path.
+     */
+    private getNode;
+}
+
+export { ConfigResolver, type ConfigTree, type ConfigVariant, isConfigVariant };

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { PathType } from '@axi-engine/utils';
+
+/**
+ * Represents a specific configuration variant that can extend another variant.
+ * @template T The base type of the configuration object.
+ */
+type ConfigVariant<T extends object> = {
+    /** Path to a base config (or multiple configs) that this variant extends. */
+    extends?: PathType;
+    /** The specific fields that override or extend the base config. */
+    fields?: Partial<T>;
+};
+/**
+ * Represents the hierarchical structure of the configuration.
+ * It's a recursive type that can contain other trees or final variants.
+ * @template T The base type of the configuration object.
+ */
+type ConfigTree<T extends object> = {
+    [key: string]: ConfigVariant<T> | ConfigTree<T>;
+};
+/**
+ * Type guard to check if an object is a ConfigVariant.
+ */
+declare function isConfigVariant<T extends object>(obj: any): obj is ConfigVariant<T>;
+
+/**
+ * Resolves hierarchical configurations with inheritance and caching.
+ * @template TBase The base type for all configurations this resolver handles.
+ */
+declare class ConfigResolver<TBase extends object> {
+    readonly configs: ConfigTree<TBase>;
+    private cache;
+    constructor(configs: ConfigTree<TBase>);
+    /**
+     * Retrieves a fully resolved and merged configuration for a given path.
+     * @template T A specific subtype of TBase that the caller expects.
+     * @param path Path to the config, e.g., 'enemies.boss.goblin'.
+     * @returns The resolved configuration object.
+     */
+    get<T extends TBase>(path: PathType): T;
+    /**
+     * Clears the cache of resolved configurations.
+     */
+    clearCache(): void;
+    /**
+     * Recursively calculates the configuration by merging a variant with its parents.
+     */
+    private calculateConfig;
+    /**
+     * Traverses the config tree to find the node at the specified path.
+     */
+    private getNode;
+}
+
+export { ConfigResolver, type ConfigTree, type ConfigVariant, isConfigVariant };

package/dist/index.js

@@ -0,0 +1,94 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ConfigResolver: () => ConfigResolver,
+  isConfigVariant: () => isConfigVariant
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/config-resolver.types.ts
+function isConfigVariant(obj) {
+  return obj && (obj.fields !== void 0 || obj.extends !== void 0);
+}
+
+// src/config-resolver.ts
+var import_deepmerge_ts = require("deepmerge-ts");
+var import_utils = require("@axi-engine/utils");
+var ConfigResolver = class {
+  constructor(configs) {
+    this.configs = configs;
+  }
+  cache = /* @__PURE__ */ new Map();
+  /**
+   * Retrieves a fully resolved and merged configuration for a given path.
+   * @template T A specific subtype of TBase that the caller expects.
+   * @param path Path to the config, e.g., 'enemies.boss.goblin'.
+   * @returns The resolved configuration object.
+   */
+  get(path) {
+    const pathArr = (0, import_utils.ensurePathArray)(path);
+    const fullPathKey = pathArr.join(import_utils.axiSettings.pathSeparator);
+    if (this.cache.has(fullPathKey)) {
+      return this.cache.get(fullPathKey);
+    }
+    const config = this.calculateConfig(pathArr);
+    this.cache.set(fullPathKey, config);
+    return config;
+  }
+  /**
+   * Clears the cache of resolved configurations.
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+  /**
+   * Recursively calculates the configuration by merging a variant with its parents.
+   */
+  calculateConfig(path, visited = []) {
+    const node = this.getNode(path, this.configs);
+    const pathStr = path.join(import_utils.axiSettings.pathSeparator);
+    (0, import_utils.throwIf)(visited.includes(pathStr), `Cyclic dependency detected in ${pathStr}`);
+    visited.push(pathStr);
+    const parentNode = node.extends ? this.calculateConfig((0, import_utils.ensurePathArray)(node.extends), [...visited]) : {};
+    return (0, import_deepmerge_ts.deepmerge)(parentNode, node);
+  }
+  /**
+   * Traverses the config tree to find the node at the specified path.
+   */
+  getNode(path, tree) {
+    const pathStr = path.join(import_utils.axiSettings.pathSeparator);
+    const [current, ...rest] = path;
+    const node = tree[current];
+    (0, import_utils.throwIfEmpty)(node, `Can't find node with path: ${pathStr}`);
+    if (rest.length > 0) {
+      (0, import_utils.throwIf)(isConfigVariant(node), `Path leads through a variant, not a tree branch: ${pathStr}`);
+      return this.getNode(rest, node);
+    }
+    (0, import_utils.throwIf)(!isConfigVariant(node), `Path does not lead to a variant: ${pathStr}`);
+    return node;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConfigResolver,
+  isConfigVariant
+});

package/dist/index.mjs

@@ -0,0 +1,66 @@
+// src/config-resolver.types.ts
+function isConfigVariant(obj) {
+  return obj && (obj.fields !== void 0 || obj.extends !== void 0);
+}
+
+// src/config-resolver.ts
+import { deepmerge } from "deepmerge-ts";
+import { axiSettings, ensurePathArray, throwIf, throwIfEmpty } from "@axi-engine/utils";
+var ConfigResolver = class {
+  constructor(configs) {
+    this.configs = configs;
+  }
+  cache = /* @__PURE__ */ new Map();
+  /**
+   * Retrieves a fully resolved and merged configuration for a given path.
+   * @template T A specific subtype of TBase that the caller expects.
+   * @param path Path to the config, e.g., 'enemies.boss.goblin'.
+   * @returns The resolved configuration object.
+   */
+  get(path) {
+    const pathArr = ensurePathArray(path);
+    const fullPathKey = pathArr.join(axiSettings.pathSeparator);
+    if (this.cache.has(fullPathKey)) {
+      return this.cache.get(fullPathKey);
+    }
+    const config = this.calculateConfig(pathArr);
+    this.cache.set(fullPathKey, config);
+    return config;
+  }
+  /**
+   * Clears the cache of resolved configurations.
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+  /**
+   * Recursively calculates the configuration by merging a variant with its parents.
+   */
+  calculateConfig(path, visited = []) {
+    const node = this.getNode(path, this.configs);
+    const pathStr = path.join(axiSettings.pathSeparator);
+    throwIf(visited.includes(pathStr), `Cyclic dependency detected in ${pathStr}`);
+    visited.push(pathStr);
+    const parentNode = node.extends ? this.calculateConfig(ensurePathArray(node.extends), [...visited]) : {};
+    return deepmerge(parentNode, node);
+  }
+  /**
+   * Traverses the config tree to find the node at the specified path.
+   */
+  getNode(path, tree) {
+    const pathStr = path.join(axiSettings.pathSeparator);
+    const [current, ...rest] = path;
+    const node = tree[current];
+    throwIfEmpty(node, `Can't find node with path: ${pathStr}`);
+    if (rest.length > 0) {
+      throwIf(isConfigVariant(node), `Path leads through a variant, not a tree branch: ${pathStr}`);
+      return this.getNode(rest, node);
+    }
+    throwIf(!isConfigVariant(node), `Path does not lead to a variant: ${pathStr}`);
+    return node;
+  }
+};
+export {
+  ConfigResolver,
+  isConfigVariant
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@axi-engine/configs",
+  "version": "0.1.0",
+  "description": "",
+  "license": "MIT",
+  "keywords": [
+    "axi-engine",
+    "typescript",
+    "gamedev",
+    "configs"
+  ],
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "docs": "typedoc src/index.ts --out docs/api --options ../../typedoc.json",
+    "test": "echo 'No tests yet for @axi-engine/configs'"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@axi-engine/utils": "^0.1.6",
+    "deepmerge-ts": "^7.1.5"
+  }
+}