@node-3d/addon-tools 10.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Blanco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,252 @@
+# Addon Tools
+
+This is a part of [Node3D](https://github.com/node-3d) project.
+
+[![NPM](https://badge.fury.io/js/%40node-3d%2Faddon-tools.svg)](https://badge.fury.io/js/@node-3d/addon-tools)
+[![Lint](https://github.com/node-3d/addon-tools/actions/workflows/lint.yml/badge.svg)](https://github.com/node-3d/addon-tools/actions/workflows/lint.yml)
+[![Test](https://github.com/node-3d/addon-tools/actions/workflows/test.yml/badge.svg)](https://github.com/node-3d/addon-tools/actions/workflows/test.yml)
+[![Cpplint](https://github.com/node-3d/addon-tools/actions/workflows/cpplint.yml/badge.svg)](https://github.com/node-3d/addon-tools/actions/workflows/cpplint.yml)
+
+```console
+npm install @node-3d/addon-tools
+```
+
+Addon Tools provide build-time and run-time helpers for Node.js C++ addons.
+- C++ shortcuts to replace repetitive code in method/class
+declaration and commonly used calls (such as `console.log`).
+- JS helpers to deliver the precompiled addons to end-users during npm install.
+- Common Logger for both C++ and JS sides with additional control,
+compared to native (`printf/cout`) and console logging.
+
+## include/addon-tools.hpp
+
+Macros and helpers for C++ addons using **NAPI**.
+See more detailed [docs here](doc).
+
+Example of a C++ method definition using Addon Tools:
+
+```c++
+// hpp:
+#include <addon-tools.hpp>
+DBG_EXPORT JS_METHOD(doSomething);
+// cpp:
+DBG_EXPORT JS_METHOD(doSomething) { NAPI_ENV;
+	LET_INT32_ARG(0, param0);
+	Napi::Value args[2] = { JS_STR("param0:"), JS_NUM(param0) };
+	consoleLog(env, 2, &args[0]);
+	RET_UNDEFINED;
+}
+```
+
+Also, ES5 class helpers allow exporting a JS class directly from C++:
+generated wrappers validate the JS receiver before dispatching to the native
+instance, while exposing `unwrap()` for lower-level manual probing.
+
+```cpp
+// hpp:
+#include <addon-tools.hpp>
+class MyClass {
+DECLARE_ES5_CLASS(MyClass, MyClass);
+public:
+	static void init(Napi::Env env, Napi::Object exports);
+	explicit MyClass(const Napi::CallbackInfo& info);
+	~MyClass();
+private:
+	JS_DECLARE_GETTER(MyClass, a);
+	JS_DECLARE_GETTER(MyClass, b);
+	JS_DECLARE_METHOD(MyClass, test);
+};
+
+// cpp:
+IMPLEMENT_ES5_CLASS(MyClass);
+
+void MyClass::init(Napi::Env env, Napi::Object exports) {
+	Napi::Function ctor = wrap(env);
+	JS_ASSIGN_GETTER(a);
+	JS_ASSIGN_GETTER(b);
+	JS_ASSIGN_METHOD(test);
+	exports.Set("MyClass", ctor);
+}
+
+MyClass::MyClass(const Napi::CallbackInfo &info) {
+	super(info);
+}
+
+MyClass::~MyClass() {}
+
+JS_IMPLEMENT_GETTER(MyClass, a) { NAPI_ENV;
+	RET_NUM(10);
+}
+
+JS_IMPLEMENT_GETTER(MyClass, b) { NAPI_ENV;
+	RET_NUM(20);
+}
+
+JS_IMPLEMENT_METHOD(MyClass, test) { NAPI_ENV;
+	consoleLog("test");
+	RET_STR("test");
+}
+
+Napi::Object init(Napi::Env env, Napi::Object exports) {
+	MyClass::init(env, exports);
+	return exports;
+}
+
+NODE_API_MODULE(myaddon, init)
+```
+
+## JS Addon Helpers
+
+### Example for an ADDON's **index.js**:
+
+Get the platform-specific directory name to import the `ADDON.node` file.
+
+```js
+	import { createRequire } from 'node:module';
+	import { getBin } from '@node-3d/addon-tools';
+
+	const require = createRequire(import.meta.url);
+	const core = require(`./${getBin()}/ADDON`);
+```
+
+
+### Example for **binding.gyp**:
+
+Using the include directories for both Addon Tools header
+and Addon API header:
+
+```gyp
+	'include_dirs': [
+		'<!@(node -e "import(\'@node-3d/addon-tools\').then((m) => m.printInclude())")',
+	],
+```
+
+> NOTE: the optional `node-addon-api` dependency is used by the `getInclude()`
+helper. If not found,
+	the **napi.h** include path won't be a part of the returned string.
+
+Using helpers for paths to dependency libs and own binaries:
+
+```gyp
+	'variables': {
+		'bin': '<!(node -e "import(\'@node-3d/addon-tools\').then((m) => m.printBin())")',
+		'gl_include': '<!(node -p "require(\'@node-3d/deps-opengl\').include")',
+		'gl_bin': '<!(node -p "require(\'@node-3d/deps-opengl\').bin")',
+	},
+```
+
+
+### Example of `cpbin` in **package.json :: scripts**:
+
+Copy the addon file, for example, from `./src/build/Release/glfw.node`
+to `./bin-windows/glfw.node`, but each platform uses a different folder.
+
+```json
+"build": "cd src && node-gyp rebuild -j max --silent && node -e \"import('@node-3d/addon-tools').then((m) => m.cpbin('glfw'))\"",
+"build-only": "cd src && node-gyp build -j max --silent && node -e \"import('@node-3d/addon-tools').then((m) => m.cpbin('glfw'))\"",
+```
+
+### Example of `cpcpplint` in **cpplint.yml**:
+
+Since all my addons use the same codestyle, I don't keep
+copies of the [CPPLINT config](utils/CPPLINT.cfg) in
+every addon. If that same config fits for you,
+here's how it can be used:
+
+```yml
+- name: Run Cpplint
+  run: |
+    node -e "import('@node-3d/addon-tools').then((m) => m.cpcpplint())"
+    cpplint --recursive ./src/cpp
+```
+
+### Example of `cpclangformat` in **package.json :: scripts**:
+
+Since all my addons use the same C++ formatting style, I don't keep
+copies of the [.clang-format config](utils/.clang-format) in every addon.
+If that same config fits for you, here's how it can be used:
+
+```json
+"format:src": "node -e \"import('@node-3d/addon-tools').then((m) => m.cpclangformat())\" && clang-format -i \"src/cpp/**/*.{cpp,hpp}\"",
+"format:src:ci": "node -e \"import('@node-3d/addon-tools').then((m) => m.cpclangformat())\" && clang-format --dry-run --Werror \"src/cpp/**/*.{cpp,hpp}\""
+```
+
+### Example of `install` in **install.js**:
+
+Downloads the addon (for example, from GitHub releases) and places
+it into a platform-specific folder.
+
+```js
+import { install } from '@node-3d/addon-tools';
+
+const prefix = 'https://github.com/node-3d/glfw/releases/download';
+const tag = '5.5.0';
+install(`${prefix}/${tag}`);
+```
+
+## JS Utils
+
+JavaScript helpers for Node.js addon development. The short list of helpers:
+
+```js
+	'getBin', 'getPlatform', 'getInclude', 'getPaths',
+	'install', 'cpbin', 'download', 'copy', 'exists',
+	'ensuredir', 'subdirs', 'subfiles', 'traverse',
+	'rmdir', 'rm', 'actionPack', 'checkGypi',
+	'createLogger', 'setLevel', 'getLevel', 'getLoggers',
+```
+
+The public JS helpers are:
+
+* `getPaths(dir)` - return `{ bin, include }` for a dependency package and prepend `bin`
+  to `PATH` on Windows.
+* `getBin()`, `printBin()` - current platform binary directory, such as `bin-windows`.
+* `getPlatform()`, `printPlatform()` - current platform key.
+* `getInclude()`, `printInclude()` - include flags for addon-tools and optional
+  `node-addon-api`.
+* `cpbin(name)` - copy `src/build/Release/<name>.node` into the platform `bin-*` directory.
+* `cpcpplint()` - copy the shared `CPPLINT.cfg` into the current directory.
+* `cpclangformat()` - copy the shared `.clang-format` into the current directory.
+* `checkGypi(path?)` - verify a local `common.gypi` matches the shared one.
+* `install(folderUrl)` - download and unpack `<platform>.gz` into the current platform bin dir.
+* `download(url)` - fetch a URL into a `Buffer`.
+* `copy`, `exists`, `ensuredir`, `subdirs`, `subfiles`, `traverse`, `rmdir`, `rm`.
+* `actionPack()` - pack the current platform bin directory as `<platform>.gz`.
+
+### Logger:
+
+This helper provides simple logging interface, for both JS and C++, that may be used
+locally or globally.
+
+```js
+	// to `console` by default
+	const logger = utils.createLogger({ name: 'my-logger' });
+```
+
+Now the following JS calls are equal:
+
+```js
+	logger.warn(1, 2, '3');
+	global.AddonTools.log('my-logger', 'warn', 1, 2, '3');
+	const { getLogger } = await import('@node-3d/addon-tools');
+	getLogger('my-logger').warn(1, 2, '3');
+```
+
+And the C++ calls are:
+
+```cpp
+	globalLog(env, "my-logger", "warn", "string log message");
+	// or
+	Napi::Value args[3] = { JS_NUM(1), JS_NUM(2), JS_STR("3") };
+	globalLog(env, "cpp", "warn", 3, &args[0]);
+```
+
+Logger helpers:
+
+* `createLogger({ name, ...methods })` - create or update a named logger.
+* `getLogger(name)` - get an existing logger or create one with console methods.
+* `setLevel(level | null)` and `getLevel()` - control global log filtering.
+* `getLoggers()` - return the logger registry snapshot.
+
+`global.AddonTools.log(name, level, ...args)` is installed for C++ helpers that need to
+route log messages back into JavaScript.

package/dist/include.d.ts

@@ -0,0 +1,12 @@
+type TAddonPaths = {
+    bin: string;
+    include: string;
+};
+export declare const getPaths: (dir: string) => TAddonPaths;
+export declare const getBin: () => string;
+export declare const printBin: () => void;
+export declare const getPlatform: () => string;
+export declare const printPlatform: () => void;
+export declare const getInclude: () => string;
+export declare const printInclude: () => void;
+export {};

package/dist/include.js

@@ -0,0 +1,43 @@
+import node_path from "node:path";
+import { fileURLToPath } from "node:url";
+const nameWindows = 'windows';
+const platformAndArch = `${process.platform}-${process.arch}`;
+const platformNames = {
+    'win32-x64': nameWindows,
+    'linux-x64': 'linux',
+    'darwin-x64': 'osx',
+    'linux-arm64': 'aarch64'
+};
+const platformName = platformNames[platformAndArch] || platformAndArch;
+const isWindows = platformName === nameWindows;
+const getPaths = (dir)=>{
+    const dirFws = dir.replaceAll('\\', '/');
+    const bin = `${dirFws}/bin-${platformName}`;
+    const include = `${dirFws}/include`;
+    if (isWindows) process.env.path = `${bin};${process.env.path ? `${process.env.path}` : ''}`;
+    return {
+        bin,
+        include
+    };
+};
+const getBin = ()=>`bin-${platformName}`;
+const printBin = ()=>console.log(getBin());
+const getPlatform = ()=>platformName;
+const printPlatform = ()=>console.log(getPlatform());
+const getNodeAddonApiIncludeDir = ()=>{
+    try {
+        const packageUrl = import.meta.resolve('node-addon-api/package.json');
+        const packageDir = node_path.dirname(fileURLToPath(packageUrl));
+        return node_path.relative('.', packageDir).replaceAll('\\', '/');
+    } catch  {
+        return '';
+    }
+};
+const getInclude = ()=>{
+    const rootPath = node_path.resolve(`${import.meta.dirname}/..`).replaceAll('\\', '/');
+    const napiInclude = getNodeAddonApiIncludeDir();
+    const thisInclude = `${rootPath}/include`;
+    return `${napiInclude} ${thisInclude}`.trim();
+};
+const printInclude = ()=>console.log(getInclude());
+export { getBin, getInclude, getPaths, getPlatform, printBin, printInclude, printPlatform };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './include.ts';
+export * from './utils/index.ts';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./include.js";
+export * from "./utils/index.js";
+globalThis.AddonTools ??= {};

package/dist/utils/action-pack.d.ts

@@ -0,0 +1 @@
+export declare const actionPack: () => Promise<void>;

package/dist/utils/action-pack.js

@@ -0,0 +1,16 @@
+import { promisify } from "node:util";
+import { exec } from "node:child_process";
+import { getBin, getPlatform } from "../include.js";
+import { getLogger } from "./logger.js";
+const action_pack_exec = promisify(exec);
+const logger = getLogger('addon-tools');
+const actionPack = async ()=>{
+    try {
+        await action_pack_exec(`cd ${getBin()} && tar -czf ../${getPlatform()}.gz *`);
+        logger.log(`pack=${getPlatform()}.gz`);
+    } catch (error) {
+        logger.error(error);
+        process.exitCode = 1;
+    }
+};
+export { actionPack };

package/dist/utils/check-gypi.d.ts

@@ -0,0 +1 @@
+export declare const checkGypi: (localPath?: string) => void;

package/dist/utils/check-gypi.js

@@ -0,0 +1,10 @@
+import { readFileSync } from "node:fs";
+import node_path from "node:path";
+const normalize = (text)=>text.replaceAll('\r\n', '\n');
+const checkGypi = (localPath = 'src/common.gypi')=>{
+    const canonicalPath = node_path.join(import.meta.dirname, '../../utils/common.gypi');
+    const local = normalize(readFileSync(localPath, 'utf8'));
+    const canonical = normalize(readFileSync(canonicalPath, 'utf8'));
+    if (local !== canonical) throw new Error(`${localPath} does not match ${canonicalPath}`);
+};
+export { checkGypi };

package/dist/utils/cpbin.d.ts

@@ -0,0 +1 @@
+export declare const cpbin: (name: string) => Promise<void>;

package/dist/utils/cpbin.js

@@ -0,0 +1,18 @@
+import promises from "node:fs/promises";
+import { getBin } from "../include.js";
+import { copy, exists, rm } from "./files.js";
+import { getLogger } from "./logger.js";
+const logger = getLogger('addon-tools');
+const cpbin = async (name)=>{
+    const srcDir = process.cwd().replaceAll('\\', '/');
+    if (!await exists(`${srcDir}/build/Release/${name}.node`)) logger.error(`Error. File "${srcDir}/build/Release/${name}.node" not found.`);
+    const binAbs = `${srcDir}/../${getBin()}`;
+    if (!await exists(binAbs)) await promises.mkdir(binAbs, {
+        recursive: true
+    });
+    const destAbs = `${binAbs}/${name}.node`;
+    if (await exists(destAbs)) await rm(destAbs);
+    await copy(`${srcDir}/build/Release/${name}.node`, destAbs);
+    logger.log(`The binary "${name}.node" was copied to "${getBin()}".`);
+};
+export { cpbin };

package/dist/utils/cpclangformat.d.ts

@@ -0,0 +1 @@
+export declare const cpclangformat: () => Promise<void>;

package/dist/utils/cpclangformat.js

@@ -0,0 +1,11 @@
+import { copy, exists } from "./files.js";
+import { getLogger } from "./logger.js";
+const logger = getLogger('addon-tools');
+const cpclangformat = async ()=>{
+    const configDest = `${process.cwd()}/.clang-format`.replaceAll('\\', '/');
+    const configSrc = `${import.meta.dirname}/../../utils/.clang-format`.replaceAll('\\', '/');
+    if (!await exists(configSrc)) return void logger.error('Error. File ".clang-format" not found.');
+    await copy(configSrc, configDest);
+    logger.log(`".clang-format" was copied to "${configDest}".`);
+};
+export { cpclangformat };

package/dist/utils/cpcpplint.d.ts

@@ -0,0 +1 @@
+export declare const cpcpplint: () => Promise<void>;

package/dist/utils/cpcpplint.js

@@ -0,0 +1,12 @@
+import { copy, exists } from "./files.js";
+import { getLogger } from "./logger.js";
+const logger = getLogger('addon-tools');
+const cpcpplint = async ()=>{
+    const cpplintDest = `${process.cwd()}/CPPLINT.cfg`.replaceAll('\\', '/');
+    const cpplintSrc = `${import.meta.dirname}/../../utils/CPPLINT.cfg`.replaceAll('\\', '/');
+    if (!await exists(cpplintSrc)) return void logger.error('Error. File "CPPLINT.cfg" not found.');
+    if (await exists(cpplintDest)) logger.warn('Warning. Dest "CPPLINT.cfg" exists and will be overwritten.');
+    await copy(cpplintSrc, cpplintDest);
+    logger.log(`"CPPLINT.cfg" was copied to "${cpplintDest}".`);
+};
+export { cpcpplint };

package/dist/utils/download.d.ts

@@ -0,0 +1 @@
+export declare const download: (url: string) => Promise<Buffer>;

package/dist/utils/download.js

@@ -0,0 +1,6 @@
+const download = async (url)=>{
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`Response status was ${response.status}`);
+    return Buffer.from(await response.arrayBuffer());
+};
+export { download };

package/dist/utils/files.d.ts

@@ -0,0 +1,8 @@
+export declare const copy: (src: string, dest: string) => Promise<void>;
+export declare const exists: (name: string) => Promise<boolean>;
+export declare const ensuredir: (dir: string) => Promise<void>;
+export declare const subdirs: (name: string) => Promise<string[]>;
+export declare const subfiles: (name: string) => Promise<string[]>;
+export declare const traverse: (name: string, showDirs?: boolean) => Promise<string[]>;
+export declare const rmdir: (name: string) => Promise<void>;
+export declare const rm: (name: string) => Promise<void>;

package/dist/utils/files.js

@@ -0,0 +1,57 @@
+import promises from "node:fs/promises";
+import { getLogger } from "./logger.js";
+const logger = getLogger('addon-tools');
+const copy = async (src, dest)=>{
+    try {
+        await promises.copyFile(src, dest);
+    } catch (error) {
+        if (!(error instanceof Error && 'code' in error && 'EBUSY' === error.code)) logger.warn('WARNING\n', error);
+    }
+};
+const exists = async (name)=>{
+    try {
+        await promises.access(name);
+        return true;
+    } catch  {
+        return false;
+    }
+};
+const ensuredir = async (dir)=>{
+    if (!dir) return;
+    await promises.mkdir(dir, {
+        recursive: true
+    });
+};
+const subdirs = async (name)=>{
+    const all = await promises.readdir(name, {
+        withFileTypes: true
+    });
+    return all.filter((dirent)=>dirent.isDirectory()).map((dirent)=>dirent.name);
+};
+const subfiles = async (name)=>{
+    const all = await promises.readdir(name, {
+        withFileTypes: true
+    });
+    return all.filter((dirent)=>dirent.isFile()).map((dirent)=>`${name}/${dirent.name}`);
+};
+const traverse = async (name, showDirs = false)=>{
+    const subdirNames = await subdirs(name);
+    const dirs = subdirNames.map((dir)=>`${name}/${dir}`);
+    const nestedItems = await Promise.all(dirs.map((dir)=>traverse(dir, showDirs)));
+    const nested = nestedItems.flat();
+    const files = await subfiles(name);
+    return [
+        ...showDirs ? dirs : [],
+        ...nested,
+        ...files
+    ];
+};
+const rmdir = async (name)=>{
+    if (await exists(name)) await promises.rm(name, {
+        recursive: true
+    });
+};
+const rm = async (name)=>{
+    if (await exists(name)) await promises.rm(name);
+};
+export { copy, ensuredir, exists, rm, rmdir, subdirs, subfiles, traverse };

package/dist/utils/index.d.ts

@@ -0,0 +1,9 @@
+export * from './action-pack.ts';
+export * from './check-gypi.ts';
+export * from './cpbin.ts';
+export * from './cpclangformat.ts';
+export * from './cpcpplint.ts';
+export * from './download.ts';
+export * from './files.ts';
+export * from './install.ts';
+export * from './logger.ts';

package/dist/utils/index.js

@@ -0,0 +1,9 @@
+export * from "./action-pack.js";
+export * from "./check-gypi.js";
+export * from "./cpbin.js";
+export * from "./cpclangformat.js";
+export * from "./cpcpplint.js";
+export * from "./download.js";
+export * from "./files.js";
+export * from "./install.js";
+export * from "./logger.js";

package/dist/utils/install.d.ts

@@ -0,0 +1 @@
+export declare const install: (folderUrl: string) => Promise<boolean>;

package/dist/utils/install.js

@@ -0,0 +1,43 @@
+import { exec } from "node:child_process";
+import promises from "node:fs/promises";
+import { promisify } from "node:util";
+import { getBin, getPlatform } from "../include.js";
+import { exists, rm, rmdir } from "./files.js";
+import { getLogger } from "./logger.js";
+const install_exec = promisify(exec);
+const logger = getLogger('addon-tools');
+const download = async (url)=>{
+    const { stderr } = await install_exec([
+        'curl -sL -o',
+        `${getBin()}/${getPlatform()}.gz`,
+        url
+    ].join(' '));
+    if (stderr) logger.warn(stderr);
+};
+const unpack = async (gzPath, binPath)=>{
+    const { stderr } = await install_exec(`tar -xzf ${gzPath} --directory ${binPath}`);
+    if (stderr) logger.warn(stderr);
+};
+const install = async (folderUrl)=>{
+    const binPath = getBin();
+    const urlPath = `${folderUrl}/${getPlatform()}.gz`;
+    const gzPath = `${binPath}/${getPlatform()}.gz`;
+    await rmdir(binPath);
+    await promises.mkdir(binPath, {
+        recursive: true
+    });
+    try {
+        await download(urlPath);
+        if (!await exists(gzPath)) {
+            logger.warn(`Could not download "${urlPath}" to "${gzPath}"`);
+            return false;
+        }
+        await unpack(gzPath, binPath);
+    } catch (error) {
+        logger.warn(error);
+        return false;
+    }
+    await rm(gzPath);
+    return true;
+};
+export { install };

package/dist/utils/logger.d.ts

@@ -0,0 +1,21 @@
+type LoggerFn = (...args: unknown[]) => void;
+type LoggerLevel = 'error' | 'warn' | 'info' | 'log' | 'debug';
+type LoggerLevelOrNull = LoggerLevel | null;
+type Logger = Record<LoggerLevel, LoggerFn> & {
+    replace: (level: string, fn: LoggerFn) => void;
+};
+type LoggerOptions = Partial<Record<LoggerLevel, LoggerFn>> & {
+    name: string;
+};
+type AddonToolsGlobal = {
+    log?: (name: string, level: LoggerLevel, ...args: unknown[]) => void;
+};
+declare global {
+    var AddonTools: AddonToolsGlobal | undefined;
+}
+export declare const createLogger: (opts: LoggerOptions) => Logger;
+export declare const setLevel: (levelOrNull: LoggerLevelOrNull) => void;
+export declare const getLevel: () => LoggerLevelOrNull;
+export declare const getLoggers: () => Record<string, Logger>;
+export declare const getLogger: (name: string) => Logger;
+export {};

package/dist/utils/logger.js

@@ -0,0 +1,62 @@
+global.AddonTools ??= {};
+const loggers = {};
+const levels = [
+    null,
+    'error',
+    'warn',
+    'info',
+    'log',
+    'debug'
+];
+let currentLevel = 'log';
+const levelIdx = {};
+for(let i = 0; i < levels.length; i++)levelIdx[levels[i] ?? 'null'] = i;
+const wrapOutput = (outputFn, level)=>(...args)=>{
+        const outputLevel = levelIdx[level] ?? 0;
+        const activeLevel = levelIdx[currentLevel ?? 'null'] ?? 0;
+        if (outputLevel > activeLevel) return;
+        outputFn(...args);
+    };
+const isLoggerLevel = (value)=>'error' === value || 'warn' === value || 'info' === value || 'log' === value || 'debug' === value;
+const assignMethods = (logger, methods)=>{
+    for (const [k, v] of Object.entries(methods))if (isLoggerLevel(k) && v) logger.replace(k, v);
+};
+const createLogger = (opts)=>{
+    const prev = loggers[opts.name];
+    if (prev) {
+        assignMethods(prev, opts);
+        return prev;
+    }
+    const newLogger = {
+        debug: console.debug,
+        log: console.log,
+        info: console.info,
+        warn: console.warn,
+        error: console.error,
+        replace: (level, fn)=>{
+            if (levelIdx[level]) newLogger[level] = wrapOutput(fn || console.log, level);
+        }
+    };
+    assignMethods(newLogger, opts);
+    loggers[opts.name] = newLogger;
+    return newLogger;
+};
+const setLevel = (levelOrNull)=>{
+    if (levels.includes(levelOrNull)) currentLevel = levelOrNull;
+};
+const getLevel = ()=>currentLevel;
+const getLoggers = ()=>({
+        ...loggers
+    });
+const getLogger = (name)=>loggers[name] || createLogger({
+        name
+    });
+if (!global.AddonTools.log) global.AddonTools.log = (name, level, ...args)=>{
+    const logger = loggers[name];
+    if (!logger) return;
+    logger[level](...args);
+};
+createLogger({
+    name: 'addon-tools'
+});
+export { createLogger, getLevel, getLogger, getLoggers, setLevel };

package/dist/utils/oxfmt.d.ts

@@ -0,0 +1,3 @@
+import type { Oxfmtrc } from 'oxfmt';
+declare const _default: Oxfmtrc;
+export default _default;