@cldmv/slothlet 2.9.0 → 2.10.0

package/types/dist/lib/helpers/metadata-api.d.mts

@@ -0,0 +1,132 @@
+export namespace metadataAPI {
+    /**
+     * Get metadata of the function that called the current function.
+     *
+     * @function caller
+     * @memberof metadataAPI
+     * @returns {object|null} Caller's metadata object or null if not found
+     * @public
+     *
+     * @description
+     * Uses stack trace analysis to identify the calling function and retrieve
+     * its attached metadata. Useful for implementing access control where a
+     * function needs to verify the identity/permissions of its caller.
+     *
+     * Stack trace structure:
+     * - Line 0: Error
+     * - Line 1: metadataAPI.caller (this function)
+     * - Line 2: Current function (the one checking)
+     * - Line 3: The caller we want to identify
+     *
+     * @example
+     * // In a secure function
+     * import { metadataAPI } from "@cldmv/slothlet/runtime";
+     *
+     * export function getSecrets() {
+     *     const caller = metadataAPI.caller();
+     *
+     *     if (!caller?.trusted) {
+     *         throw new Error("Access denied: untrusted caller");
+     *     }
+     *
+     *     if (!caller.permissions?.includes("read_secrets")) {
+     *         throw new Error("Access denied: insufficient permissions");
+     *     }
+     *
+     *     return { apiKey: "secret123", token: "xyz" };
+     * }
+     *
+     * @example
+     * // With custom metadata tags
+     * const caller = metadataAPI.caller();
+     * console.log("Caller source:", caller?.sourceFolder);
+     * console.log("Caller version:", caller?.version);
+     * console.log("Caller author:", caller?.author);
+     */
+    function caller(): object | null;
+    /**
+     * Get metadata of the current function.
+     *
+     * @function self
+     * @memberof metadataAPI
+     * @returns {object|null} Current function's metadata or null if not found
+     * @public
+     *
+     * @description
+     * Retrieves metadata attached to the currently executing function. Useful
+     * for functions that need to inspect their own metadata (e.g., for logging,
+     * conditional behavior based on load source).
+     *
+     * Stack trace structure:
+     * - Line 0: Error
+     * - Line 1: metadataAPI.self (this function)
+     * - Line 2: Current function (the one we want to identify)
+     *
+     * @example
+     * // Function checking its own metadata
+     * import { metadataAPI } from "@cldmv/slothlet/runtime";
+     *
+     * export function smartFunction() {
+     *     const meta = metadataAPI.self();
+     *
+     *     if (meta?.environment === "development") {
+     *         console.log("Running in development mode");
+     *     }
+     *
+     *     if (meta?.version) {
+     *         console.log(`Function version: ${meta.version}`);
+     *     }
+     *
+     *     return "result";
+     * }
+     */
+    function self(): object | null;
+    /**
+     * Get metadata of any function by API path.
+     *
+     * @function get
+     * @memberof metadataAPI
+     * @param {string} path - Dot-notation API path (e.g., "math.add", "plugins.helper")
+     * @param {object} [apiRoot] - Optional API root object (uses runtime.self if not provided)
+     * @returns {object|null} Function's metadata or null if not found
+     * @public
+     *
+     * @description
+     * Retrieves metadata for any function in the API tree by its path. Useful
+     * for checking metadata of functions you have references to, or for
+     * administrative/introspection purposes.
+     *
+     * @example
+     * // Check metadata of a specific function
+     * import { metadataAPI } from "@cldmv/slothlet/runtime";
+     *
+     * export function checkPermissions() {
+     *     const pluginMeta = metadataAPI.get("plugins.userPlugin");
+     *
+     *     if (!pluginMeta) {
+     *         throw new Error("Plugin not found or has no metadata");
+     *     }
+     *
+     *     if (pluginMeta.trusted) {
+     *         console.log("Plugin is trusted");
+     *     } else {
+     *         console.log("Plugin is untrusted");
+     *     }
+     * }
+     *
+     * @example
+     * // Iterate and check all plugins
+     * const pluginPaths = ["plugins.auth", "plugins.logger", "plugins.cache"];
+     * for (const path of pluginPaths) {
+     *     const meta = metadataAPI.get(path);
+     *     console.log(`${path}: ${meta?.version || "unknown"}`);
+     * }
+     *
+     * @example
+     * // From outside slothlet context, pass API root explicitly
+     * const api = await slothlet({ dir: "./modules" });
+     * const meta = await metadataAPI.get("plugins.helper", api);
+     */
+    function get(path: string, apiRoot?: object): object | null;
+}
+//# sourceMappingURL=metadata-api.d.mts.map

package/types/dist/lib/helpers/metadata-api.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-api.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/metadata-api.mjs"],"names":[],"mappings":";IAmNC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,mBAvCa,MAAM,GAAC,IAAI,CAgEvB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,iBA/Ba,MAAM,GAAC,IAAI,CAsDvB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6CG;IACH,mBAzCW,MAAM,YACN,MAAM,GACJ,MAAM,GAAC,IAAI,CAsDvB"}

package/types/dist/lib/helpers/multidefault.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"multidefault.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/multidefault.mjs"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yDAlBW,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC,WACrB,MAAM,YAEd;IAA0B,KAAK,GAAvB,OAAO;IACe,QAAQ,GAA9B,MAAM,GAAC,IAAI;CACnB,GAAU,OAAO,CAAC;IAChB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yBAAyB,EAAE,OAAO,CAAC;IACnC,oBAAoB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,kBAAkB,EAAE,KAAK,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CACjE,CAAC,CA8FJ;AAED;;;;;;;;GAQG;AACH,0DALW,MAAM,GACJ,OAAO,CAWnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,4DAvBG;IAAyB,yBAAyB,EAA1C,OAAO;IACU,gBAAgB,EAAjC,OAAO;IACU,iBAAiB,EAAlC,OAAO;IACgB,UAAU,EAAjC,KAAK,CAAC,MAAM,CAAC;IACG,UAAU,EAA1B,MAAM;IACU,gBAAgB,EAAhC,MAAM;IACY,KAAK,GAAvB,OAAO;CACf,GAAU;IACR,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAA;CACf,CA4FH"}
+{"version":3,"file":"multidefault.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/multidefault.mjs"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yDAlBW,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC,WACrB,MAAM,YAEd;IAA0B,KAAK,GAAvB,OAAO;IACe,QAAQ,GAA9B,MAAM,GAAC,IAAI;CACnB,GAAU,OAAO,CAAC;IAChB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yBAAyB,EAAE,OAAO,CAAC;IACnC,oBAAoB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,kBAAkB,EAAE,KAAK,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;CACjE,CAAC,CAuGJ;AAED;;;;;;;;GAQG;AACH,0DALW,MAAM,GACJ,OAAO,CAWnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,4DAvBG;IAAyB,yBAAyB,EAA1C,OAAO;IACU,gBAAgB,EAAjC,OAAO;IACU,iBAAiB,EAAlC,OAAO;IACgB,UAAU,EAAjC,KAAK,CAAC,MAAM,CAAC;IACG,UAAU,EAA1B,MAAM;IACU,gBAAgB,EAAhC,MAAM;IACY,KAAK,GAAvB,OAAO;CACf,GAAU;IACR,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAA;CACf,CA4FH"}

package/types/dist/lib/runtime/runtime-asynclocalstorage.d.mts

@@ -60,6 +60,8 @@ export const context: object;
  * console.log(reference); // Current reference data
  */
 export const reference: object;
+export { metadataAPI };
 export type AsyncLocalStorageType = AsyncLocalStorage<any>;
+import { metadataAPI } from "@cldmv/slothlet/helpers/metadata-api";
 import { AsyncLocalStorage } from "node:async_hooks";
 //# sourceMappingURL=runtime-asynclocalstorage.d.mts.map

package/types/dist/lib/runtime/runtime-asynclocalstorage.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-asynclocalstorage.d.mts","sourceRoot":"","sources":["../../../../dist/lib/runtime/runtime-asynclocalstorage.mjs"],"names":[],"mappings":"AAuCA;;;;;GAKG;AACH,wBAHU,qBAAqB,CAGkB;AAEjD;;;;;GAKG;AACH,yBAHU,qBAAqB,CAGmB;AAsB3C,gCAdI,MAAM,yBAEN,GAAG,gBAED,GAAG,CAwGf;AAiBM,0BAZM,MAAM,GAAC,IAAI,CAY0B;AAkN3C,iCAjBI,MAAM,YAiJhB;AA2TD;;;;;;;;;;;;;GAaG;AACH,mBATU,WAAS,MAAM,CAS6B;AAEtD;;;;;;;;;;;;;GAaG;AACH,sBATU,MAAM,CAS4C;AAE5D;;;;;;;;;;;;;GAaG;AACH,wBATU,MAAM,CASgD;;kCAp1B9B,kBAAkB"}
+{"version":3,"file":"runtime-asynclocalstorage.d.mts","sourceRoot":"","sources":["../../../../dist/lib/runtime/runtime-asynclocalstorage.mjs"],"names":[],"mappings":"AAwCA;;;;;GAKG;AACH,wBAHU,qBAAqB,CAGkB;AAEjD;;;;;GAKG;AACH,yBAHU,qBAAqB,CAGmB;AAsB3C,gCAdI,MAAM,yBAEN,GAAG,gBAED,GAAG,CAwGf;AAiBM,0BAZM,MAAM,GAAC,IAAI,CAY0B;AAkN3C,iCAjBI,MAAM,YAiJhB;AA2TD;;;;;;;;;;;;;GAaG;AACH,mBATU,WAAS,MAAM,CAS6B;AAEtD;;;;;;;;;;;;;GAaG;AACH,sBATU,MAAM,CAS4C;AAE5D;;;;;;;;;;;;;GAaG;AACH,wBATU,MAAM,CASgD;;;4BAl1BpC,sCAAsC;kCAHhC,kBAAkB"}

package/types/dist/lib/runtime/runtime-livebindings.d.mts

@@ -63,5 +63,7 @@ export namespace contextManager {
     export { setContext as set };
     export { runWithCtx };
 }
+export { metadataAPI };
 import { AsyncLocalStorage } from "node:async_hooks";
+import { metadataAPI } from "@cldmv/slothlet/helpers/metadata-api";
 //# sourceMappingURL=runtime-livebindings.d.mts.map

package/types/dist/lib/runtime/runtime-livebindings.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-livebindings.d.mts","sourceRoot":"","sources":["../../../../dist/lib/runtime/runtime-livebindings.mjs"],"names":[],"mappings":"AA+SA;;;;;;;;;GASG;AACH,gCANW,MAAM,yBAEN,GAAG,gBAED,GAAG,CAoFf;AAED;;;;;;GAMG;AACH,iCAHW,MAAM,YAiEhB;AAID;;;GAGG;AAEH,kCAEC;AAED,kDASC;AA/bD;;;;;GAKG;AACH,gDAAkD;AA8ClD;;;;;GAKG;AACH,mBAHU,MAAM,CAmDd;AAEF;;;;;GAKG;AACH,sBAHU,MAAM,CA0Dd;AAEF;;;;;GAKG;AACH,wBAHU,MAAM,CA+Cd;AAEF;;;;;GAKG;AACH,yBAHU,MAAM,CAkCd;;;;;;kCA5QgC,kBAAkB"}
+{"version":3,"file":"runtime-livebindings.d.mts","sourceRoot":"","sources":["../../../../dist/lib/runtime/runtime-livebindings.mjs"],"names":[],"mappings":"AAgTA;;;;;;;;;GASG;AACH,gCANW,MAAM,yBAEN,GAAG,gBAED,GAAG,CAoFf;AAED;;;;;;GAMG;AACH,iCAHW,MAAM,YAiEhB;AAID;;;GAGG;AAEH,kCAEC;AAED,kDASC;AA/bD;;;;;GAKG;AACH,gDAAkD;AA8ClD;;;;;GAKG;AACH,mBAHU,MAAM,CAmDd;AAEF;;;;;GAKG;AACH,sBAHU,MAAM,CA0Dd;AAEF;;;;;GAKG;AACH,wBAHU,MAAM,CA+Cd;AAEF;;;;;GAKG;AACH,yBAHU,MAAM,CAkCd;;;;;;;kCA7QgC,kBAAkB;4BAOxB,sCAAsC"}

package/types/dist/lib/runtime/runtime.d.mts

@@ -6,4 +6,5 @@ export const context: {};
 export const reference: {};
 export const instanceId: any;
 export const sharedALS: any;
+export const metadataAPI: {};
 //# sourceMappingURL=runtime.d.mts.map

package/types/dist/lib/runtime/runtime.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.mts","sourceRoot":"","sources":["../../../../dist/lib/runtime/runtime.mjs"],"names":[],"mappings":"AAoMA,4EAGC;AAED,gDAGC;AAED,8BAGC;AArKA,6BAA+B;AAkDhC,yBAiDE;AAEF,2BAiDE;AAiBF,6BAOK;AAEL,4BAAuD"}
+{"version":3,"file":"runtime.d.mts","sourceRoot":"","sources":["../../../../dist/lib/runtime/runtime.mjs"],"names":[],"mappings":"AAoMA,4EAGC;AAED,gDAGC;AAED,8BAGC;AArKA,6BAA+B;AAkDhC,yBAiDE;AAEF,2BAiDE;AAiBF,6BAOK;AAEL,4BAAuD;AAGvD,6BAQE"}

package/types/dist/slothlet.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"slothlet.d.mts","sourceRoot":"","sources":["../../dist/slothlet.mjs"],"names":[],"mappings":"AA0LA;;;;;;;GAOG;AACH,mBAJU,MAAM,CAIO;AAEvB;;;;;GAKG;AACH,sBAJU,MAAM,CAIU;AAE1B;;;;;GAKG;AACH,wBAJU,MAAM,CAIY;;;;;;;;;UAsmCd,MAAM;;;;;;WAIN,OAAO;;;;;;;;WAGP,MAAM;;;;;;;;aAKN,MAAM;;;;;;;cAKN,MAAM;;;;;;;eAIN,MAAM;;;;;;;;YAIN,OAAO;;;;;;;eAKP,MAAM;;;;;;;wBAIN,OAAO;;;;;;cAIP,MAAM;;;;;;gBAGN,MAAM;;;;;;eAMjB;QAA8B,UAAU,GAA7B,OAAO;QACY,gBAAgB,GAAnC,OAAO;QACY,gBAAgB,GAAnC,OAAO;QACW,KAAK,GAClC;YAAqC,KAAK,GAA/B,MAAM,EAAE;YACkB,gBAAgB,GAA1C,MAAM,EAAE;YACkB,KAAK,GAA/B,MAAM,EAAE;YACkB,KAAK,GAA/B,MAAM,EAAE;SACrB;KAAA;;;;;;cAIa,MAAM,OAAO,CAAC,IAAI,CAAC;;;;YACnB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC;;;;cACtD,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,MAAM,GAAC,MAAM,CAAC,EAAE,GAAC,MAAM,GAAC,OAAO,CAAC,MAAM,CAAC,CAAC;;AAjqC/E;;;;;;;;GAQG;AACH,mCAJW,eAAe,GACb,OAAO,CAAC,WAAW,CAAC,CAiChC"}
+{"version":3,"file":"slothlet.d.mts","sourceRoot":"","sources":["../../dist/slothlet.mjs"],"names":[],"mappings":"AA+LA;;;;;;;GAOG;AACH,mBAJU,MAAM,CAIO;AAEvB;;;;;GAKG;AACH,sBAJU,MAAM,CAIU;AAE1B;;;;;GAKG;AACH,wBAJU,MAAM,CAIY;;;;;;;;;UA2oCd,MAAM;;;;;;WAIN,OAAO;;;;;;;;WAGP,MAAM;;;;;;;;aAKN,MAAM;;;;;;;cAKN,MAAM;;;;;;;eAIN,MAAM;;;;;;;;YAIN,OAAO;;;;;;;eAKP,MAAM;;;;;;;wBAIN,OAAO;;;;;;cAIP,MAAM;;;;;;gBAGN,MAAM;;;;;;eAMjB;QAA8B,UAAU,GAA7B,OAAO;QACY,gBAAgB,GAAnC,OAAO;QACY,gBAAgB,GAAnC,OAAO;QACW,KAAK,GAClC;YAAqC,KAAK,GAA/B,MAAM,EAAE;YACkB,gBAAgB,GAA1C,MAAM,EAAE;YACkB,KAAK,GAA/B,MAAM,EAAE;YACkB,KAAK,GAA/B,MAAM,EAAE;SACrB;KAAA;;;;;;cAIa,MAAM,OAAO,CAAC,IAAI,CAAC;;;;YACnB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC;;;;cACtD,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,MAAM,GAAC,MAAM,CAAC,EAAE,GAAC,MAAM,GAAC,OAAO,CAAC,MAAM,CAAC,CAAC;;AAtsC/E;;;;;;;;GAQG;AACH,mCAJW,eAAe,GACb,OAAO,CAAC,WAAW,CAAC,CAiChC"}