@sanatanai/require 1.0.1

package/README.md

@@ -0,0 +1,134 @@
+<img style="max-width: 300px; margin-left: auto; margin-right: auto" src="https://raw.githubusercontent.com/ShivamSharma999/Sanatan-AI-Welcome/refs/heads/master/logo.png" alt="Sanatan AI logo" />
+
+# Sanatan AI - Require
+
+Sanatan AI - Require is a powerful and flexible module import system that extends Node.js's native `require` functionality. It offers enhanced control over module resolution, allowing you to configure how `package-lock.json` is utilized, whether local `node_modules` are considered, and provides mechanisms for introspection and cache management. This package is designed to give developers more granular control and insight into their application's dependency loading.
+
+## Installation
+
+You can install Sanatan AI - Require via npm:
+
+```bash
+npm install @sanatanai/require
+```
+
+## Usage
+
+The primary way to use Sanatan AI - Require is through its `require` function, which works asynchronously.
+
+```javascript
+import require from "@sanatanai/require";
+
+async function loadModule() {
+    try {
+        const myModule = await require('my-package');
+        console.log('Module loaded:', myModule);
+    } catch (error) {
+        console.error('Failed to load module:', error);
+    }
+}
+
+loadModule();
+```
+
+## Configuration (setRequire)
+
+The `setRequire` interface provides methods to configure the behavior of the `require` function.
+
+### `setRequire.readPkgLock(v: boolean)`
+
+Sets whether the `package-lock.json` file specified by `setRequire.pkgLockPath` should be read for module resolution.
+- `v`: A boolean value. `true` to enable reading `package-lock.json`, `false` to disable.
+- Default: `true`
+
+```javascript
+import { setRequire } from "@sanatanai/require";
+
+// Disable reading package-lock.json
+setRequire.readPkgLock(false);
+```
+
+### `setRequire.pkgLockPath(p: string)`
+
+Sets the absolute or relative path to the `package-lock.json` file.
+- `p`: The path to `package-lock.json`.
+- Default: `root/package-lock.json` (where root is the project's root directory)
+
+```javascript
+import { setRequire } from "@sanatanai/require";
+
+// Set a custom path for package-lock.json
+setRequire.pkgLockPath('/path/to/my/custom/package-lock.json');
+```
+
+### `setRequire.nodeModules(v: boolean)`
+
+Sets whether the local `node_modules` folder should be used for importing modules.
+- `v`: A boolean value. `true` to enable using local `node_modules`, `false` to disable.
+- Default: `false`
+
+```javascript
+import { setRequire } from "@sanatanai/require";
+
+// Enable using local node_modules
+setRequire.nodeModules(true);
+```
+
+### `setRequire.clearCache()`
+
+Clears the internal cache of `package.json` files that Sanatan AI - Require stores for different packages. This can be useful for development scenarios where `package.json` files might change frequently.
+
+```javascript
+import { setRequire } from "@sanatanai/require";
+
+// Clear the internal file cache
+setRequire.clearCache();
+```
+
+## Information Retrieval (getRequire)
+
+The `getRequire` interface provides methods to retrieve the current configuration and internal state of the `require` function.
+
+### `getRequire.readPkgLock(): boolean`
+
+Returns the current boolean value indicating whether `package-lock.json` is being read. This value is configured by `setRequire.readPkgLock`.
+
+```javascript
+import { getRequire } from "@sanatanai/require";
+
+const isReadingPkgLock = getRequire.readPkgLock();
+console.log('Is reading package-lock.json:', isReadingPkgLock);
+```
+
+### `getRequire.pkgLockPath(): string`
+
+Returns the currently configured path to the `package-lock.json` file. This path is set by `setRequire.pkgLockPath`.
+
+```javascript
+import { getRequire } from "@sanatanai/require";
+
+const pkgLockPath = getRequire.pkgLockPath();
+console.log('Package-lock.json path:', pkgLockPath);
+```
+
+### `getRequire.importMap(): Map<string, object>`
+
+Returns the internal `Map` object used by Sanatan AI - Require for module imports. Each entry in the map typically represents a mapping from a module name to its script path or metadata.
+
+```javascript
+import { getRequire } from "@sanatanai/require";
+
+const importMap = getRequire.importMap();
+console.log('Current import map:', importMap);
+```
+
+### `getRequire.cache(): Map<string, object>`
+
+Returns the file cache `Map` object stored internally by the Sanatan AI `require` function. This cache stores parsed `package.json` contents for performance.
+
+```javascript
+import { getRequire } from "@sanatanai/require";
+
+const fileCache = getRequire.cache();
+console.log('Internal file cache:', fileCache);
+```

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@sanatanai/require",
+  "version": "1.0.1",
+  "description": "The browser side nodejs require function.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShivamSharma999/require.git"
+  },
+  "scripts": {},
+  "keywords": [
+    "require",
+    "es6",
+    "nodejs",
+    "sanatan ai require",
+    "sanatan require"
+  ],
+  "author": "Sanatan AI",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,69 @@
+interface setRequire {
+    /**
+     * Set whether to read `package-lock.json` specified in `setRequire.pkgPath`
+     * @param v boolean telling whether to read or not. Default is `true`
+     */
+    readPkgLock: (v: boolean) => void;
+    /**
+     * Sets the path to `package-lock.json`
+     * @param p The path to `package-lock.json`. Default is root/package-lock.json
+     */
+    pkgLockPath: (p: string) => void;
+    /**
+     * Sets whether to use local `node_modules` folder for importing modules
+     * @param v Boolean telling whether to use local modules or not. Default is false
+     */
+    nodeModules: (v: boolean) => void;
+    /**
+     * ### Clears the stored file cache.
+     * package.json of different packages are stored in form of a Map object, this function clears it
+     */
+    clearCache: () => void;
+}
+
+interface getRequire {
+    /**
+     * Returns the value of boolean which tell whether to read `package-lock.json`
+     * It can be configured by `setRequire.readPkgLock`
+     */
+    readPkgLock: () => boolean;
+    /**
+     * Returns the path to `package-lock.json` specified by `setRequire.pkgLockPath`
+     */
+    pkgLockPath: () => string;
+    /**
+     * Returns the Map object created by sanatanai for imports.
+     * 
+     * Each is in pair "moduleName": "scriptPath"
+     */
+    importMap: () => Map<string, object>
+    /**
+     * Returns the file cache map object stored by Sanatan AI require function.
+     */
+    cache: () => Map<string, object>
+}
+
+
+/**
+ * Asynchronously imports a module using Sanatan AI's custom resolution logic.
+ * This function extends Node.js's native `require` with additional capabilities
+ * configured via `setRequire` and inspectable via `getRequire`.
+ *
+ * The resolution process can be influenced by:
+ * - `package-lock.json`: Whether to read `package-lock.json` for module versions (controlled by `setRequire.readPkgLock`).
+ * - `pkgLockPath`: The specific path to the `package-lock.json` file (controlled by `setRequire.pkgLockPath`).
+ * - `nodeModules`: Whether to consider local `node_modules` folders for module lookup (controlled by `setRequire.nodeModules`).
+ *
+ * The function also leverages an internal cache for `package.json` files, which can be cleared using `setRequire.clearCache()`.
+ *
+ * @param module The name or path of the module to import. This can be a package name (e.g., 'lodash'),
+ *               a relative path (e.g., './myModule'), or an absolute path.
+ * @returns A Promise that resolves to the imported module's content. The type `any` is used here
+ *          as the module content can vary greatly (objects, functions, primitives).
+ * @throws {Error} If the module cannot be resolved or loaded for any reason (e.g., file not found,
+ *                 syntax error in the module, or issues with package-lock resolution).
+ */
+declare function require(module: string): Promise<any>
+
+export { setRequire, getRequire, require }
+export default require

package/src/index.js

@@ -0,0 +1,73 @@
+"use strict";
+
+let readPkgLock = true,
+    pkgLockPath = "/package-lock.json",
+    nodeModules = false;
+
+const importMap = new Map(),
+    cache = new Map(),
+    script = document.createElement("script");
+
+script.id = "sanatan-require sanatan-script";
+script.type = "importmap";
+document.body.appendChild(script);
+
+const setRequire = {
+    readPkgLock: (v) => readPkgLock = v,
+    pkgLockPath: (p) => pkgLockPath = p,
+    nodeModules: (v) => nodeModules = v,
+    clearCache: () => cache.clear()
+}
+
+const getRequire = {
+    readPkgLock: () => readPkgLock,
+    pkgLockPath: () => pkgLockPath,
+    importMap: () => importMap,
+    cache: () => cache
+}
+
+function updateImportMap(pkg, path) {
+    importMap.set(pkg, path);
+    const importJson = {};
+    importMap.forEach((s, p) => importJson[p] = s);
+    script.innerHTML = JSON.stringify({ "imports": importJson }, null, 2);
+}
+
+async function loadPkg(packagePath, packageName, imp = true) {
+    let pkg;
+    if (!cache.has(packageName)) {
+        const req = await fetch(packagePath);
+        pkg = await req.json();
+        cache.set(packageName, pkg);
+    } else {
+        pkg = cache.get(packageName);
+    }
+    let scriptRoot = packagePath.replace(/package.json$/, "");
+    scriptRoot = scriptRoot.startsWith("https") ? scriptRoot : ((scriptRoot.startsWith("/") || scriptRoot.startsWith("./")) ? scriptRoot : "/" + scriptRoot);
+    let scriptPath = pkg.module ? pkg.module : (pkg.type == "module" ? (pkg.main || "index.js") : "index.js");
+    scriptPath = (scriptPath.startsWith("/") || scriptPath.startsWith("./")) ? scriptPath.replace(/\.{0,1}\//, "") : scriptPath;
+    updateImportMap(packageName, scriptRoot + scriptPath);
+    return imp ? await import(packageName) : {};
+}
+
+async function require(module) {
+    if (readPkgLock && pkgLockPath && !importMap.has(module)) {
+        let pkgLck = await fetch(pkgLockPath);
+        pkgLck = await pkgLck.json();
+        Object.keys(pkgLck.packages).forEach(pack => {
+            if (pack !== "") {
+                pack = nodeModules ? pack : pack.replace("node_modules/", "");
+                const packJson = (nodeModules ? pack : "https://unpkg.com/" + pack) + "/package.json";
+                loadPkg(packJson, module, false);
+            }
+        });
+        return await loadPkg(nodeModules ? `node_modules/${module}/package.json` : `https://unpkg.com/${module}/package.json`, module)
+    }
+    else if (importMap.has(module)) return await import(module)
+    else {
+        return await loadPkg("https://unpkg.com/" + module + "/package.json");
+    }
+}
+
+export { setRequire, getRequire, require }
+export default require