@cldmv/slothlet 1.0.1 → 2.0.1

package/dist/lib/helpers/resolve-from-caller.mjs

@@ -0,0 +1,141 @@
+/*
+	Copyright 2025 CLDMV/Shinrai
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.
+*/
+
+
+
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+
+
+
+export const toFsPath = (v) => (v && String(v).startsWith("file://") ? fileURLToPath(String(v)) : v ? String(v) : null);
+
+
+export function getStack(skipFn) {
+	const orig = Error.prepareStackTrace;
+	try {
+		Error.prepareStackTrace = (_, s) => s; 
+		const e = new Error("Stack trace");
+		if (skipFn) Error.captureStackTrace(e, skipFn);
+		return e.stack || [];
+	} finally {
+		Error.prepareStackTrace = orig;
+	}
+}
+
+const THIS_FILE = fileURLToPath(import.meta.url);
+const THIS_DIR = path.dirname(THIS_FILE);
+
+
+
+
+
+
+
+
+function pickPrimaryBaseFile() {
+	const files = [];
+	for (const cs of getStack(pickPrimaryBaseFile)) {
+		const f = toFsPath(cs?.getFileName?.());
+		if (!f) continue;
+		if (f.startsWith?.("node:internal")) continue;
+		files.push(f);
+	}
+
+	let iSloth = -1;
+	for (let i = 0; i < files.length; i++) {
+		if (path.basename(files[i]).toLowerCase() === "slothlet.mjs") iSloth = i;
+	}
+	if (iSloth !== -1) {
+		const j = iSloth + 1;
+		if (j < files.length) {
+			const b = path.basename(files[j]).toLowerCase();
+			if (/^index\.(mjs|cjs|js)$/.test(b) && j + 1 < files.length) return files[j + 1];
+			return files[j];
+		}
+	}
+	return null;
+}
+
+
+function pickFallbackBaseFile() {
+	for (const cs of getStack(pickFallbackBaseFile)) {
+		const f = toFsPath(cs?.getFileName?.());
+		if (!f) continue;
+		if (f.startsWith?.("node:internal")) continue;
+		if (f === THIS_FILE) continue;
+		if (f.startsWith(THIS_DIR + path.sep)) continue; 
+		if (path.basename(f).toLowerCase() === "slothlet.mjs") continue;
+		return f;
+	}
+	return THIS_FILE;
+}
+
+
+
+
+function resolveWith(rel, makePrimary, exists, makeFallback) {
+	if (typeof rel !== "string") throw new TypeError("rel must be a string");
+
+	
+	const primaryBase = pickPrimaryBaseFile() ?? pickFallbackBaseFile();
+	const primary = makePrimary(primaryBase, rel);
+	if (exists(primary)) return primary;
+
+	const fbBase = pickFallbackBaseFile();
+	return makeFallback(fbBase, rel);
+}
+
+
+
+
+export function resolvePathFromCaller(rel) {
+	
+	if (rel.startsWith?.("file://")) return fileURLToPath(rel);
+	if (path.isAbsolute(rel)) return rel;
+
+	return resolveWith(
+		rel,
+		
+		(baseFile, r) => path.resolve(path.dirname(baseFile), r),
+		
+		(candidate) => fs.existsSync(candidate),
+		
+		(baseFile, r) => path.resolve(path.dirname(baseFile), r)
+	);
+}
+
+
+export function resolveUrlFromCaller(rel) {
+	
+	if (rel.startsWith?.("file://")) return rel;
+	if (path.isAbsolute(rel)) return pathToFileURL(rel).href;
+
+	return resolveWith(
+		rel,
+		
+		(baseFile, r) => new URL(r, pathToFileURL(baseFile)).href,
+		
+		(href) => fs.existsSync(fileURLToPath(href)),
+		
+		(baseFile, r) => new URL(r, pathToFileURL(baseFile)).href
+	);
+}
+
+

package/dist/lib/helpers/sanitize.mjs

@@ -0,0 +1,78 @@
+/*
+	Copyright 2025 CLDMV/Shinrai
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.
+*/
+
+
+
+
+export function sanitizePathName(input, opts = {}) {
+	const { lowerFirst = true, rules = {} } = opts;
+
+	const L = (rules.leave || []).map((s) => String(s).toLowerCase());
+	const U = (rules.upper || []).map((s) => String(s).toLowerCase());
+	const W = (rules.lower || []).map((s) => String(s).toLowerCase());
+
+	const isValidId = (s) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(s);
+
+	let s = String(input).trim();
+
+	
+	if (isValidId(s)) return s;
+
+	
+	let parts = s.split(/[^A-Za-z0-9_$]+/).filter(Boolean);
+	if (parts.length === 0) return "_";
+
+	
+	
+	while (parts.length && !/^[A-Za-z_$]/.test(parts[0][0])) {
+		parts[0] = parts[0].replace(/^[^A-Za-z_$]+/, "");
+		if (!parts[0]) parts.shift();
+	}
+	if (parts.length === 0) return "_";
+
+	const applyRule = (seg, index) => {
+		const key = seg.toLowerCase();
+
+		
+		if (L.includes(key)) return seg;
+
+		
+		if (U.includes(key)) return seg.toUpperCase();
+
+		
+		if (W.includes(key)) return seg.toLowerCase();
+
+		
+		if (index === 0) {
+			
+			return lowerFirst ? seg[0].toLowerCase() + seg.slice(1) : seg;
+		}
+		
+		return seg[0].toUpperCase() + seg.slice(1);
+	};
+
+	
+	let out = parts.map((seg, i) => applyRule(seg.replace(/[^A-Za-z0-9_$]/g, ""), i)).join("");
+
+	
+	out = out.replace(/[^A-Za-z0-9_$]/g, "");
+	if (!out || !/^[A-Za-z_$]/.test(out[0])) out = "_" + out;
+
+	return out;
+}
+
+
+

package/dist/lib/modes/slothlet_eager.mjs

@@ -0,0 +1,80 @@
+/*
+	Copyright 2025 CLDMV/Shinrai
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.
+*/
+
+
+
+
+
+import fs from "fs/promises";
+import path from "path";
+
+
+
+
+
+
+export async function create(dir, rootLevel = true, maxDepth = Infinity, currentDepth = 0) {
+	
+	const entries = await fs.readdir(dir, { withFileTypes: true });
+	const api = {};
+	
+	const rootNamedExports = {};
+	
+	let rootDefaultFunction = null;
+
+	if (rootLevel) {
+		for (const entry of entries) {
+			if (this._shouldIncludeFile(entry)) {
+				const ext = path.extname(entry.name);
+				const fileName = path.basename(entry.name, ext);
+				const apiKey = this._toApiKey(fileName);
+				const mod = await this._loadSingleModule(path.join(dir, entry.name), true);
+				if (mod && typeof mod.default === "function") {
+					if (!rootDefaultFunction) rootDefaultFunction = mod.default;
+					for (const [key, value] of Object.entries(mod)) {
+						if (key !== "default") api[key] = value;
+					}
+				} else {
+					api[apiKey] = mod;
+					for (const [key, value] of Object.entries(mod)) {
+						rootNamedExports[key] = value;
+					}
+				}
+			}
+		}
+	}
+
+	for (const entry of entries) {
+		if (entry.isDirectory() && !entry.name.startsWith(".") && currentDepth < maxDepth) {
+			const categoryPath = path.join(dir, entry.name);
+			api[this._toApiKey(entry.name)] = await this._loadCategory(categoryPath, currentDepth + 1, maxDepth);
+		}
+	}
+
+	let finalApi;
+	if (rootDefaultFunction) {
+		Object.assign(rootDefaultFunction, api);
+		finalApi = rootDefaultFunction;
+	} else {
+		finalApi = api;
+	}
+
+	
+	
+	
+
+	return finalApi;
+}

package/dist/lib/modes/slothlet_lazy.mjs

@@ -0,0 +1,342 @@
+/*
+	Copyright 2025 CLDMV/Shinrai
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.
+*/
+
+
+import fs from "fs/promises";
+import path from "path";
+import { runWithCtx } from "@cldmv/slothlet/runtime";
+
+
+export async function create(dir, rootLevel = true, maxDepth = Infinity, currentDepth = 0) {
+	const instance = this; 
+	const entries = await fs.readdir(dir, { withFileTypes: true });
+	let api = {};
+	let rootDefaultFn = null;
+
+	
+	if (rootLevel) {
+		for (const entry of entries) {
+			if (instance._shouldIncludeFile(entry)) {
+				const ext = path.extname(entry.name);
+				const fileName = path.basename(entry.name, ext);
+				const apiKey = instance._toApiKey(fileName);
+				const mod = await instance._loadSingleModule(path.join(dir, entry.name), true);
+				if (mod && typeof mod.default === "function") {
+					if (!rootDefaultFn) rootDefaultFn = mod.default;
+					for (const [k, v] of Object.entries(mod)) {
+						if (k !== "default") api[k] = v;
+					}
+				} else {
+					api[apiKey] = mod;
+				}
+			}
+		}
+	}
+
+	
+	if (rootDefaultFn) {
+		Object.assign(rootDefaultFn, api);
+		api = rootDefaultFn;
+	}
+
+	
+	for (const entry of entries) {
+		if (entry.isDirectory() && !entry.name.startsWith(".") && currentDepth < maxDepth) {
+			const key = instance._toApiKey(entry.name);
+			const subDirPath = path.join(dir, entry.name);
+			const parent = api;
+			const depth = 1; 
+			const proxy = createFolderProxy({
+				subDirPath,
+				key,
+				parent,
+				instance,
+				depth,
+				maxDepth,
+				pathParts: [key]
+			});
+			parent[key] = proxy;
+		}
+	}
+
+	return api;
+}
+
+
+function replacePlaceholder(parent, key, placeholder, value, instance, depth) {
+	if (!parent || !key) return;
+	if (parent[key] !== placeholder) return; 
+
+	
+	let finalKey = key;
+	if (typeof value === "function" && value.name && value.name.toLowerCase() === key.toLowerCase() && value.name !== key) {
+		
+		finalKey = value.name;
+
+		
+		if (finalKey !== key && key in parent) {
+			try {
+				delete parent[key];
+			} catch {
+				
+			}
+		}
+	}
+
+	try {
+		Object.defineProperty(parent, finalKey, { value, writable: true, enumerable: true, configurable: true });
+	} catch {
+		parent[finalKey] = value; 
+	}
+	if (instance?.config?.debug) {
+		console.log(`[lazy][materialize] replaced ${key}${finalKey !== key ? ` -> ${finalKey}` : ""} (${typeof value})`);
+	}
+	if (depth === 1 && typeof instance?.updateBoundApiProperty === "function") {
+		instance.updateBoundApiProperty(finalKey, parent[finalKey]);
+	}
+}
+
+
+function createFolderProxy({ subDirPath, key, parent, instance, depth, maxDepth, pathParts }) {
+	let materialized = null;
+	let inFlight = null;
+
+	
+	async function _materialize() {
+		if (materialized) return materialized;
+		if (inFlight) return inFlight;
+		
+		
+		const lazy_materializeCategory = async () => {
+			const value = await instance._buildCategory(subDirPath, {
+				currentDepth: depth,
+				maxDepth,
+				mode: "lazy",
+				subdirHandler: ({ subDirPath: nestedPath, key: nestedKey, categoryModules, currentDepth: cd, maxDepth: md }) =>
+					createFolderProxy({
+						subDirPath: nestedPath,
+						key: nestedKey,
+						parent: categoryModules,
+						instance,
+						depth: cd + 1,
+						maxDepth: md,
+						pathParts: [...pathParts, nestedKey]
+					})
+			});
+			materialized = value;
+			if (instance?.config?.debug) {
+				try {
+					const infoKeys = materialized && typeof materialized === "object" ? Object.keys(materialized) : [];
+					const todayType = materialized && materialized.today ? typeof materialized.today : "n/a";
+					console.log(
+						`[lazy][debug] materialized key='${key}' path='${subDirPath}' type=${typeof materialized} keys=${JSON.stringify(
+							infoKeys
+						)} todayType=${todayType}`
+					);
+				} catch {
+					
+				}
+			}
+			
+			replacePlaceholder(parent, key, placeholder, materialized, instance, depth);
+			
+			if (instance.config.debug) {
+				try {
+					const type = typeof materialized;
+					const keys = type === "object" && materialized ? Object.keys(materialized) : [];
+					console.log(
+						`[lazy][debug] materialized '${pathParts.join("/")}' -> type=${type} keys=${JSON.stringify(keys)} parentHas=${
+							parent[key] === materialized
+						}`
+					);
+				} catch {
+					
+				}
+			}
+			placeholder.__materialized = materialized;
+			return materialized;
+		};
+		inFlight = lazy_materializeCategory();
+		try {
+			return await inFlight;
+		} finally {
+			inFlight = null;
+		}
+	}
+
+	
+	async function lazy_invoke(thisArg, ...args) {
+		const value = await _materialize();
+		if (typeof value === "function") {
+			
+			const ctx = instance.boundapi?.__ctx;
+			if (ctx) {
+				return runWithCtx(ctx, value, thisArg, args);
+			} else {
+				return value.apply(thisArg, args);
+			}
+		}
+		
+		
+		return value;
+	}
+
+	
+	
+	function lazy_lazyTarget(...args) {
+		return lazy_invoke(this, ...args);
+	}
+	
+	Object.defineProperty(lazy_lazyTarget, "__materialized", { value: null, writable: true, enumerable: false, configurable: true });
+	
+	Object.defineProperty(lazy_lazyTarget, "__slothletPath", { value: subDirPath, enumerable: false, configurable: true });
+	
+	Object.defineProperty(lazy_lazyTarget, "_materialize", { value: _materialize, enumerable: false, configurable: true, writable: true });
+
+	
+	try {
+		Object.defineProperty(lazy_lazyTarget, "name", { value: `lazyFolder_${key}`, configurable: true });
+	} catch {
+		
+	}
+
+	const placeholder = new Proxy(lazy_lazyTarget, {
+		apply(_t, thisArg, args) {
+			return lazy_invoke(thisArg, ...args);
+		},
+		get(_t, prop, _) {
+			if (prop === "__materialized") return materialized;
+			if (prop === "_materialize") return _materialize;
+			if (prop === "then") return undefined; 
+			
+			if (materialized) {
+				if (materialized && (typeof materialized === "object" || typeof materialized === "function")) return materialized[prop];
+				return undefined;
+			}
+			
+			if (!inFlight) inFlight = _materialize();
+			
+			
+			
+			
+			return new Proxy(
+				
+				function lazy_propertyAccessor(...args) {
+					return inFlight.then(
+						
+						function lazy_handleResolvedValue(resolved) {
+							const value = resolved ? resolved[prop] : undefined;
+							if (typeof value === "function") {
+								
+								const ctx = instance.boundapi?.__ctx;
+								if (ctx) {
+									return runWithCtx(ctx, value, this, args);
+								} else {
+									return value.apply(this, args);
+								}
+							}
+							return value;
+						}
+					);
+				},
+				{
+					
+					get(target, subProp) {
+						if (subProp === "name") return `lazy_${prop}`;
+						if (subProp === "length") return 0;
+						
+						return new Proxy(
+							 function lazy_deepPropertyAccessor() {},
+							{
+								apply(target, thisArg, args) {
+									
+									if (materialized) {
+										const value = materialized[prop];
+										if (value && typeof value[subProp] === "function") {
+											
+											const ctx = instance.boundapi?.__ctx;
+											if (ctx) {
+												return runWithCtx(ctx, value[subProp], thisArg, args);
+											} else {
+												return value[subProp].apply(thisArg, args);
+											}
+										}
+										return value ? value[subProp] : undefined;
+									}
+
+									
+									if (!inFlight) inFlight = _materialize();
+									return inFlight.then(
+										
+										function lazy_handleDeepResolvedValue(resolved) {
+											const value = resolved ? resolved[prop] : undefined;
+											if (value && typeof value[subProp] === "function") {
+												
+												const ctx = instance.boundapi?.__ctx;
+												if (ctx) {
+													return runWithCtx(ctx, value[subProp], thisArg, args);
+												} else {
+													return value[subProp].apply(thisArg, args);
+												}
+											}
+											return value ? value[subProp] : undefined;
+										}
+									);
+								}
+							}
+						);
+					}
+				}
+			);
+		},
+		has(_t, prop) {
+			if (materialized && (typeof materialized === "object" || typeof materialized === "function")) return prop in materialized;
+			return false;
+		},
+		ownKeys() {
+			const baseKeys = Reflect.ownKeys(lazy_lazyTarget); 
+			if (!materialized) return baseKeys;
+			if (typeof materialized === "object" || typeof materialized === "function") {
+				const matKeys = Reflect.ownKeys(materialized);
+				return Array.from(new Set([...baseKeys, ...matKeys]));
+			}
+			return baseKeys;
+		},
+		getOwnPropertyDescriptor(_t, prop) {
+			if (prop === "_materialize") {
+				
+				return Reflect.getOwnPropertyDescriptor(lazy_lazyTarget, "_materialize");
+			}
+			if (prop === "__materialized") {
+				return { configurable: true, enumerable: false, writable: true, value: materialized };
+			}
+			if (prop === "prototype") {
+				
+				return Object.getOwnPropertyDescriptor(lazy_lazyTarget, "prototype");
+			}
+			if (materialized && (typeof materialized === "object" || typeof materialized === "function")) {
+				const d = Object.getOwnPropertyDescriptor(materialized, prop);
+				if (d) return { ...d, configurable: true };
+			}
+			
+			const td = Object.getOwnPropertyDescriptor(lazy_lazyTarget, prop);
+			if (td) return { ...td, configurable: true };
+			return undefined;
+		}
+	});
+
+	return placeholder;
+}