@cldmv/slothlet 1.0.0 → 1.0.3

package/package.json

@@ -1,15 +1,21 @@
 {
 	"name": "@cldmv/slothlet",
-	"version": "1.0.0",
+	"version": "1.0.3",
 	"description": "Slothlet: Lazy Modular API Loader for Node.js. Dynamically loads API modules and submodules only when accessed, supporting both lazy and eager loading.",
 	"main": "slothlet.mjs",
 	"exports": {
-		".": "./slothlet.mjs"
+		".": {
+			"types": "./types/slothlet.d.ts",
+			"import": "./slothlet.mjs",
+			"default": "./slothlet.mjs"
+		}
 	},
+	"types": "./types/slothlet.d.ts",
 	"directories": {
 		"test": "tests"
 	},
 	"scripts": {
+		"publish": "npm publish --access public",
 		"test": "vitest run",
 		"testjest": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js"
 	},
@@ -51,6 +57,10 @@
 	},
 	"files": [
 		"README.md",
-		"LICENSE"
-	]
+		"LICENSE",
+		"types/"
+	],
+	"dependencies": {
+		"typescript": "^5.9.2"
+	}
 }

package/slothlet.mjs

@@ -14,7 +14,6 @@
 import fs from "fs/promises";
 import path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
-import { createEngine, setShutdown } from "./src/lib/slothlet_engine.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -90,11 +89,12 @@ export const slothlet = {
 		let dispose;
 		if (mode === "singleton") {
 			const { context = null, reference = null, ...loadConfig } = options;
-			await slothlet.load(loadConfig, { context, reference });
+			await this.load(loadConfig, { context, reference });
 			// console.log("this.boundapi", this.boundapi);
 			// process.exit(0);
 			return this.boundapi;
 		} else {
+			const { createEngine } = await import("./src/lib/slothlet_engine.mjs");
 			({ api, dispose } = await createEngine({ entry, ...options }));
 			// setShutdown(dispose); // stash the disposer so shutdown() can call it
 			// Attach __dispose__ as a non-enumerable property to the API object
@@ -211,7 +211,11 @@ export const slothlet = {
 		this.config = { ...this.config, ...config };
 		// console.log("this.config", this.config);
 		// process.exit(0);
-		const apiDir = this.config.dir || __dirname;
+		let apiDir = this.config.dir || __dirname;
+		// If apiDir is relative, resolve it from process.cwd() (the caller's working directory)
+		if (apiDir && !path.isAbsolute(apiDir)) {
+			apiDir = path.resolve(process.cwd(), apiDir);
+		}
 		if (this.loaded) return this.api;
 		if (this.config.lazy) {
 			this.api = await this._createLazyApiProxy(apiDir, 0);
@@ -307,6 +311,7 @@ export const slothlet = {
 	 * @private
 	 */
 	async _eagerLoadCategory(categoryPath) {
+		let flattened = false;
 		const files = await fs.readdir(categoryPath);
 		const mjsFiles = files.filter((f) => f.endsWith(".mjs") && !f.startsWith("."));
 		if (mjsFiles.length === 1) {
@@ -316,17 +321,24 @@ export const slothlet = {
 				const mod = await this._loadSingleModule(path.join(categoryPath, mjsFiles[0]));
 				// If the module is an object with only named exports, flatten them
 				if (mod && typeof mod === "object" && !mod.default) {
+					flattened = true;
 					return { ...mod };
 				}
 				return mod;
 			}
 		}
+		const categoryName = path.basename(categoryPath);
 		const categoryModules = {};
 		for (const file of mjsFiles) {
 			const moduleName = path.basename(file, ".mjs");
 			const mod = await this._loadSingleModule(path.join(categoryPath, file));
-			// For multi-file categories, always assign to property (do not flatten)
-			categoryModules[this._toApiKey(moduleName)] = mod;
+			if (moduleName === categoryName && mod && typeof mod === "object") {
+				// Flatten all exports from the file matching the folder name
+				Object.assign(categoryModules, mod);
+				flattened = true;
+			} else {
+				categoryModules[this._toApiKey(moduleName)] = mod;
+			}
 		}
 		return categoryModules;
 	},
@@ -359,6 +371,12 @@ export const slothlet = {
 		}
 
 		const moduleExports = Object.entries(module);
+		// If there are no exports, throw a clear error
+		if (!moduleExports.length) {
+			throw new Error(
+				`slothlet: No exports found in module '${modulePath}'. The file is empty or does not export any function/object/variable.`
+			);
+		}
 		if (this.config.debug) console.log("moduleExports: ", moduleExports);
 
 		// Handle both module.default and moduleExports[0][1] for callable and object default exports
@@ -722,6 +740,8 @@ export const slothlet = {
 		for (const entry of entries) {
 			if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
 
+			let flattened = false;
+
 			const categoryPath = path.join(dir, entry.name);
 			const subEntries = await fs.readdir(categoryPath, { withFileTypes: true });
 			const mjsFiles = subEntries.filter((e) => e.isFile() && e.name.endsWith(".mjs") && !e.name.startsWith("."));
@@ -743,7 +763,17 @@ export const slothlet = {
 				const moduleName = path.basename(fileEntry.name, ".mjs");
 				const modKey = self._toApiKey(moduleName);
 				const loader = createLoader(() => self._loadSingleModule(path.join(categoryPath, fileEntry.name)));
-				categoryObj[modKey] = loader;
+				if (moduleName === categoryName) {
+					// Flatten all exports from the file matching the folder name
+					loader().then((mod) => {
+						if (mod && typeof mod === "object") {
+							Object.assign(categoryObj, mod);
+						}
+					});
+					flattened = true;
+				} else {
+					categoryObj[modKey] = loader;
+				}
 			}
 			for (const subDirEntry of subDirs) {
 				categoryObj[self._toApiKey(subDirEntry.name)] = await self._createLazyApiProxy(

package/types/debug-slothlet.d.mts

@@ -0,0 +1 @@
+export {};

package/types/eslint.config.d.mts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/types/jest.config.d.mts

@@ -0,0 +1,6 @@
+declare namespace _default {
+    let testMatch: string[];
+    let testEnvironment: string;
+    let testPathIgnorePatterns: string[];
+}
+export default _default;

package/types/slothlet.d.mts

@@ -0,0 +1,189 @@
+/**
+ * Updates the live-binding references for self, context, and reference.
+ * Call this whenever a new API instance is created.
+ * Ensures submodules can import and use `self`, `context`, and `reference` directly.
+ *
+ * @param {object} newContext - The current context object to bind as `context`.
+ * @param {object} newReference - The current reference object to bind as `reference`.
+ * @param {object} newSelf - The current API object instance to bind as `self`.
+ *
+ * @example
+ * // Update live bindings after creating a new API instance
+ * updateBindings(api, { user: 'alice' }, { custom: 123 });
+ * // Submodules can now use imported self, context, reference
+ * self.math.add(1, 2);
+ * context.user; // 'alice'
+ * reference.custom; // 123
+ */
+export function updateBindings(newContext: object, newReference: object, newSelf?: object): void;
+/**
+ * Live-binding references for API object (self) and context.
+ * These are updated whenever a new API instance is created.
+ * Dynamically imported modules can access these at runtime.
+ * @type {object}
+ */
+export let self: object;
+/**
+ * Live-binding reference for contextual data.
+ * @type {object}
+ */
+export let context: object;
+/**
+ * Live-binding reference for ref data.
+ * @type {object}
+ */
+export let reference: object;
+export namespace slothlet {
+    let api: any;
+    let boundapi: any;
+    let mode: string;
+    let loaded: boolean;
+    namespace config {
+        export let lazy: boolean;
+        export let lazyDepth: number;
+        export { DEBUG as debug };
+        export let dir: any;
+    }
+    let _dispose: any;
+    let _boundAPIShutdown: any;
+    function create(options?: {}): Promise<any>;
+    /**
+     * Returns the loaded API object (Proxy or plain).
+     * @returns {object}
+     */
+    function getApi(): object;
+    /**
+     * Returns the loaded API object (Proxy or plain).
+     * @returns {object}
+     */
+    function getBoundApi(): object;
+    /**
+     * Shuts down both the bound API and internal resources, with timeout and error handling.
+     * Prevents infinite recursion if called from Proxy.
+     * @returns {Promise<void>}
+     */
+    function shutdown(): Promise<void>;
+    /**
+     * Loads the bindleApi modules, either lazily or eagerly.
+     *
+     * @param {object} [config] - Loader configuration options.
+     * @param {boolean} [config.lazy=true] - If true, enables lazy loading (API modules loaded on demand).
+     * @param {number} [config.lazyDepth=Infinity] - How deep to lazy load (subdirectory depth; use Infinity for full lazy loading).
+     * @param {string} [config.dir] - Directory to load API modules from. Defaults to the loader's directory (__dirname).
+     * @returns {Promise<object>} The API object. If lazy loading is enabled, returns a Proxy that loads modules on access; otherwise, returns a fully loaded API object.
+     *
+     * @example
+     * // Lazy load from default directory
+     * await slothlet.load({ lazy: true });
+     *
+     * // Eager load from a custom directory
+     * await slothlet.load({ lazy: false, dir: '/custom/path/to/api' });
+     *
+     * // Access API endpoints
+     * const api = slothlet.createBoundApi(ctx);
+     * const result = await api.fs.ensureDir('/some/path');
+     */
+    function load(config?: {
+        lazy?: boolean;
+        lazyDepth?: number;
+        dir?: string;
+    }, ctxRef?: {
+        context: any;
+        reference: any;
+    }): Promise<object>;
+    /**
+     * Eagerly loads all API modules (same as original loader).
+     * @param {string} dir - Directory to load
+     * @returns {Promise<object>} API object
+     * @private
+     */
+    function _eagerLoadApi(dir: string, rootLevel?: boolean): Promise<object>;
+    /**
+     * Converts a filename or folder name to camelCase for API property.
+     * @param {string} name
+     * @returns {string}
+     * @example
+     * toApiKey('root-math') // 'rootMath'
+     */
+    function _toApiKey(name: string): string;
+    /**
+     * Eagerly loads a category (same flattening logic as original).
+     * @param {string} categoryPath
+     * @returns {Promise<object>}
+     * @private
+     */
+    function _eagerLoadCategory(categoryPath: string): Promise<object>;
+    /**
+     * Loads a single module file and returns its exports (flattened if needed).
+     * @param {string} modulePath
+     * @returns {Promise<object>}
+     * @private
+     */
+    function _loadSingleModule(modulePath: string, rootLevel?: boolean): Promise<object>;
+    /**
+     * Creates a lazy API proxy for a directory.
+     * @param {string} dir - Directory path.
+     * @param {number} [depth=0] - Recursion depth.
+     * @returns {Proxy} Proxy object for lazy API loading.
+     * @private
+     */
+    function _createLazyApiProxy(dir: string, depth?: number, rootLevel?: boolean): ProxyConstructor;
+    function _createLazyApiProxy2(dir: any, depth?: number, rootLevel?: boolean): Promise<any>;
+    /**
+     * Updates the live-binding references for self and context.
+     * Call this whenever a new API instance is created.
+     * @param {object} newContext - The current context object to bind as `context`.
+     * @param {object} newReference - The current reference object to bind as `reference`.
+     * @param {object} newSelf - The current API object instance to bind as `self`.
+     */
+    function updateBindings(newContext: object, newReference: object, newSelf?: object): void;
+    /**
+     * Creates a bound API object with live-bound self, context, and reference.
+     * Ensures submodules can access `self`, `context`, and `reference` directly.
+     * Works for both eager and lazy loading modes.
+     *
+     * @param {object} [ctx=null] - Context object to be spread into the API and live-bound.
+     * @param {object|object[]} [ref=null] - Reference object(s) to extend the API/self with additional properties.
+     * @returns {object} Bound API object (Proxy or plain) with live-bound self, context, and reference.
+     *
+     * @example
+     * // Create API with context and reference
+     * const api = slothlet.createBoundApi({ user: 'alice' }, { custom: 123 });
+     *
+     * // Access API endpoints
+     * api.math.add(2, 3); // 5
+     *
+     * // Access live-bound self and context
+     * api.self.math.add(1, 2); // 3
+     * api.context.user; // 'alice'
+     * api.reference.custom; // 123
+     *
+     * // Submodules can import { self, context, reference } from the loader
+     * // and use them directly: self.math.add(...)
+     */
+    function createBoundApi(ctx?: object, ref?: object | object[]): object;
+    /**
+     * Recursively builds a bound API from an eagerly loaded API object.
+     * @param {object} apiModules
+     * @returns {object}
+     * @private
+     */
+    function _buildCompleteApi(apiModules: object): object;
+    /**
+     * Wraps the lazy API proxy so that modules are loaded and built with context on access.
+     * @param {Proxy} proxyApi
+     * @returns {Proxy}
+     * @private
+     */
+    function _createBoundLazyApi(proxyApi: ProxyConstructor): ProxyConstructor;
+    /**
+     * Checks if the API has been loaded.
+     * @returns {boolean}
+     */
+    function isLoaded(): boolean;
+}
+export default slothlet;
+/**
+ * DEBUG mode: configurable via command line (--slothletdebug), environment variable (SLOTHLET_DEBUG), or defaults to false.
+ */
+declare let DEBUG: boolean;

package/types/src/lib/slothlet_child.d.mts

@@ -0,0 +1 @@
+export {};

package/types/src/lib/slothlet_engine.d.mts

@@ -0,0 +1,6 @@
+export function setShutdown(fn: any): any;
+export function createEngine(allOptions: any): Promise<{
+    api: () => void;
+    dispose: () => Promise<void>;
+}>;
+export function makeFacade2(portal: any): () => void;

package/types/src/lib/slothlet_esm.d.mts

@@ -0,0 +1,18 @@
+/**
+ * Minimal custom ESM loader for VM context fallback when SourceTextModule is unavailable.
+ * Parses import/export statements, loads dependencies recursively, and evaluates code in context.
+ * Limitations: Only supports static imports/exports, no top-level await, no dynamic import, no advanced ESM features.
+ * @param {object} context - The VM context.
+ * @param {string} fileUrl - The file URL to load.
+ * @param {Set<string>} [visited] - Tracks loaded modules to prevent cycles.
+ * @returns {Promise<object>} Module namespace object.
+ * @example
+ * const ns = await loadEsmModuleFallback(context, 'file:///path/to/mod.mjs');
+ */
+export function loadEsmModuleFallback(context: object, fileUrl: string, visited?: Set<string>): Promise<object>;
+/**
+ * Detects if a file is ESM based on extension or code content.
+ * @param {string} fileUrl
+ * @returns {Promise<boolean>}
+ */
+export function isEsmFile(fileUrl: string): Promise<boolean>;

package/types/src/lib/slothlet_helpers.d.mts

@@ -0,0 +1,24 @@
+export function normalizeContext(ctx: any): any;
+export function installGlobalsInCurrentRealm(contextMap: any): void;
+export function extendSelfWithReference(self: any, reference: any): void;
+export function installPortalForSelf(): void;
+export function asUrl(p: any): any;
+export function isPlainObject(o: any): boolean;
+export function guessName(v: any): any;
+export function makeNodeishContext(): vm.Context;
+/**
+ * Loads a module into a VM context, supporting ESM (mjs), CJS (cjs), or auto-detection.
+ * @param {object} context - The VM context.
+ * @param {string} fileUrl - The file URL to load.
+ * @param {string} [mode='auto'] - 'auto', 'mjs', or 'cjs'.
+ * @returns {Promise<object>} Module namespace or SourceTextModule.
+ */
+export function loadEsmInVm2(context: object, fileUrl: string, mode?: string, ...args: any[]): Promise<object>;
+export function loadEsmInVm(context: any, fileUrl: any): Promise<any>;
+export function installContextGlobalsVM(context: any, userContext: any): void;
+export function bootSlothletVM(context: any, entryUrl: any, loadConfig: any, ctxRef: any): Promise<void>;
+export function marshalArgsReplaceFunctions(value: any, registerCb: any): any;
+export function reviveArgsReplaceTokens(value: any, invokeCb: any): any;
+export function containsFunction(value: any): boolean;
+export const HAS_STM: boolean;
+import vm from "node:vm";

package/types/src/lib/slothlet_worker.d.mts

@@ -0,0 +1 @@
+export {};

package/types/vitest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;