@js-utils-kit/fs 1.2.0 → 1.4.0

package/dist/index.cjs

@@ -1 +1 @@
-var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));let c=require(`fs`);c=s(c);let l=require(`path`);l=s(l);let u=require(`archiver`);u=s(u);function d({format:e,source:t,destination:n,options:r={},log:i=!0,onSuccess:a}){let o=l.default.resolve(t);if(!c.default.existsSync(o)||!c.default.statSync(o).isDirectory())throw Error(`Source directory "${t}" does not exist or is not a directory.`);let s=c.default.createWriteStream(n);e===`zip`&&(r={...r,zlib:{level:9}});let d=(0,u.default)(e,r);return new Promise((e,r)=>{s.on(`close`,()=>{let t=d.pointer();i&&console.log(`${n} created: ${t} total bytes`),a&&a(t),e()}),d.on(`error`,e=>{r(e)}),d.pipe(s),d.directory(t,!1),d.finalize().catch(e=>r(e instanceof Error?e:Error(String(e))))})}exports.createArchive=d;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));let c=require(`fs`);c=s(c);let l=require(`path`);l=s(l);let u=require(`archiver`);u=s(u);let d=require(`url`);function f({format:e,source:t,destination:n,options:r={},log:i=!0,onSuccess:a}){let o=l.default.resolve(t);if(!c.default.existsSync(o)||!c.default.statSync(o).isDirectory())throw Error(`Source directory "${t}" does not exist or is not a directory.`);let s=c.default.createWriteStream(n);e===`zip`&&(r={...r,zlib:{level:9}});let d=(0,u.default)(e,r);return new Promise((e,r)=>{s.on(`close`,()=>{let t=d.pointer();i&&console.log(`${n} created: ${t} total bytes`),a&&a(t),e()}),d.on(`error`,e=>{r(e)}),d.pipe(s),d.directory(t,!1),d.finalize().catch(e=>r(e instanceof Error?e:Error(String(e))))})}const p=typeof __filename<`u`;function m(e){if(!e)throw Error(`locateModuleFile requires import.meta.url (ESM) or __filename (CJS).`);return e.startsWith(`file:`)?(0,d.fileURLToPath)(e):e}function h(e){return l.default.dirname(m(e))}function g(e,t){let n=h(t),r=l.default.resolve(n,e);if(l.default.relative(n,r).startsWith(`..`))throw Error(`Resolved path escapes module directory.`);return r}function _(e){return e.replace(/\\/g,`/`)}function v(e){return e.replace(/\//g,`\\`)}function y(e){return e.replace(/[/\\]/g,l.default.sep)}exports.createArchive=f,exports.hasCommonJSFilename=p,exports.locateModuleDirectory=h,exports.locateModuleFile=m,exports.resolveModuleRelative=g,exports.toPlatformPath=y,exports.toPosixPath=_,exports.toWinPath=v;

package/dist/index.d.cts

@@ -33,4 +33,180 @@ declare function createArchive({
   onSuccess
 }: CreateArchiveOptions): Promise<void>;
 //#endregion
-export { createArchive };
+//#region src/env.d.ts
+/**
+ * Determines whether the current runtime provides the CommonJS `__filename` variable.
+ *
+ * @remarks
+ * - In CommonJS environments, Node.js injects a module-scoped `__filename` variable representing the absolute path of the current module file.
+ * - In pure ESM environments, `__filename` does not exist.
+ * - This helper allows environment-aware branching while remaining testable (e.g., via mocking in unit tests).
+ *
+ * @returns `true` if `__filename` is available in the current runtime; otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * if (hasCommonJSFilename) {
+ *   console.log("Running in CommonJS environment");
+ * } else {
+ *   console.log("Running in ESM environment");
+ * }
+ */
+declare const hasCommonJSFilename: boolean;
+//#endregion
+//#region src/locator.d.ts
+/**
+ * Returns the absolute file path of a module.
+ *
+ * @remarks
+ * This utility supports both:
+ * - **ESM** → pass `import.meta.url`
+ * - **CommonJS** → pass `__filename`
+ *
+ * The path MUST be explicitly provided. Automatic runtime detection is intentionally not performed to avoid incorrect module resolution.
+ *
+ * @returns Absolute path to the provided module file.
+ *
+ * @throws {Error} If `metaUrlOrPath` is not provided.
+ *
+ * @example ESM usage
+ * ```ts
+ * const file = locateModuleFile(import.meta.url);
+ * console.log(file);
+ * ```
+ *
+ * @example CommonJS usage
+ * ```ts
+ * const file = locateModuleFile(__filename);
+ * console.log(file);
+ * ```
+ */
+declare function locateModuleFile(/** `import.meta.url` (ESM) or `__filename` (CJS) */
+
+metaUrlOrPath: string): string;
+/**
+ * Returns the absolute directory path of a module.
+ *
+ * @remarks
+ * Internally derives the directory from {@link locateModuleFile}.
+ *
+ * @returns Absolute directory path.
+ *
+ * @example ESM
+ * ```ts
+ * const dir = locateModuleDirectory(import.meta.url);
+ * ```
+ *
+ * @example CommonJS
+ * ```ts
+ * const dir = locateModuleDirectory(__filename);
+ * ```
+ */
+declare function locateModuleDirectory(/** `import.meta.url` (ESM) or `__filename` (CJS) */
+
+metaUrlOrPath: string): string;
+/**
+ * Resolves a path relative to the provided module's directory.
+ *
+ * @remarks
+ * Useful for loading internal assets such as:
+ * - `.hbs` templates
+ * - JSON files
+ * - SQL schemas
+ * - bundled static resources
+ *
+ * Unlike `process.cwd()`, this resolves relative to the module
+ * file location, making it safe for usage inside `node_modules`.
+ *
+ * @returns Absolute resolved path.
+ *
+ * @throws {Error}
+ * If module path is not provided.
+ *
+ * @example ESM
+ * ```ts
+ * const templatePath = resolveModuleRelative(
+ *   "../templates/welcome.hbs",
+ *   import.meta.url
+ * );
+ * ```
+ *
+ * @example CommonJS
+ * ```ts
+ * const templatePath = resolveModuleRelative(
+ *   "../templates/welcome.hbs",
+ *   __filename
+ * );
+ * ```
+ */
+declare function resolveModuleRelative(/** Path relative to the module directory */relativePath: string, /** `import.meta.url` (ESM) or `__filename` (CJS) */metaUrlOrPath: string): string;
+//#endregion
+//#region src/path.d.ts
+/**
+ * Converts a file system path to POSIX format.
+ *
+ * @remarks
+ * - Replaces all backslashes (`\`) with forward slashes (`/`).
+ * - Does NOT perform full path normalization (e.g., resolving `.` or `..` segments).
+ *
+ * @returns The path using POSIX separators (`/`).
+ *
+ * @example
+ * ```ts
+ * toPosixPath('C:\\Users\\TenE\\project')
+ * // => 'C:/Users/TenE/project'
+ * ```
+ *
+ * @example
+ * ```ts
+ * toPosixPath('src\\utils\\file.ts')
+ * // => 'src/utils/file.ts'
+ * ```
+ */
+declare function toPosixPath(/** The path to convert */
+
+p: string): string;
+/**
+ * Converts a file system path to Windows (Win32) format.
+ *
+ * On POSIX systems (Linux/macOS), all forward slashes (`/`) are replaced with backslashes (`\`).
+ *
+ * @returns The path using Windows separators (`\`).
+ *
+ * @example
+ * ```ts
+ * toWinPath('src/utils/file.ts')
+ * // => 'src\\utils\\file.ts'
+ * ```
+ *
+ * @example
+ * ```ts
+ * toWinPath('/usr/local/bin')
+ * // => '\\usr\\local\\bin'
+ * ```
+ */
+declare function toWinPath(/** The path to convert */
+
+p: string): string;
+/**
+ * Converts a file system path to the current platform-specific format.
+ *
+ * This replaces both forward slashes (`/`) and backslashes (`\`) with the platform's separator (`path.sep`).
+ *
+ * - Windows → `\`
+ * - macOS/Linux → `/`
+ *
+ * @returns The path using the current OS separator.
+ *
+ * @example Mixed Separators
+ * ```ts
+ * toPlatformPath('src/utils/file.ts')
+ * // On Windows: 'src\\utils\\file.ts'
+ * // On POSIX:   'src/utils/file.ts'
+ * ```
+ */
+declare function toPlatformPath(/** The path to convert */
+
+p: string): string;
+//#endregion
+export { createArchive, hasCommonJSFilename, locateModuleDirectory, locateModuleFile, resolveModuleRelative, toPlatformPath, toPosixPath, toWinPath };

package/dist/index.d.mts

@@ -33,4 +33,180 @@ declare function createArchive({
   onSuccess
 }: CreateArchiveOptions): Promise<void>;
 //#endregion
-export { createArchive };
+//#region src/env.d.ts
+/**
+ * Determines whether the current runtime provides the CommonJS `__filename` variable.
+ *
+ * @remarks
+ * - In CommonJS environments, Node.js injects a module-scoped `__filename` variable representing the absolute path of the current module file.
+ * - In pure ESM environments, `__filename` does not exist.
+ * - This helper allows environment-aware branching while remaining testable (e.g., via mocking in unit tests).
+ *
+ * @returns `true` if `__filename` is available in the current runtime; otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * if (hasCommonJSFilename) {
+ *   console.log("Running in CommonJS environment");
+ * } else {
+ *   console.log("Running in ESM environment");
+ * }
+ */
+declare const hasCommonJSFilename: boolean;
+//#endregion
+//#region src/locator.d.ts
+/**
+ * Returns the absolute file path of a module.
+ *
+ * @remarks
+ * This utility supports both:
+ * - **ESM** → pass `import.meta.url`
+ * - **CommonJS** → pass `__filename`
+ *
+ * The path MUST be explicitly provided. Automatic runtime detection is intentionally not performed to avoid incorrect module resolution.
+ *
+ * @returns Absolute path to the provided module file.
+ *
+ * @throws {Error} If `metaUrlOrPath` is not provided.
+ *
+ * @example ESM usage
+ * ```ts
+ * const file = locateModuleFile(import.meta.url);
+ * console.log(file);
+ * ```
+ *
+ * @example CommonJS usage
+ * ```ts
+ * const file = locateModuleFile(__filename);
+ * console.log(file);
+ * ```
+ */
+declare function locateModuleFile(/** `import.meta.url` (ESM) or `__filename` (CJS) */
+
+metaUrlOrPath: string): string;
+/**
+ * Returns the absolute directory path of a module.
+ *
+ * @remarks
+ * Internally derives the directory from {@link locateModuleFile}.
+ *
+ * @returns Absolute directory path.
+ *
+ * @example ESM
+ * ```ts
+ * const dir = locateModuleDirectory(import.meta.url);
+ * ```
+ *
+ * @example CommonJS
+ * ```ts
+ * const dir = locateModuleDirectory(__filename);
+ * ```
+ */
+declare function locateModuleDirectory(/** `import.meta.url` (ESM) or `__filename` (CJS) */
+
+metaUrlOrPath: string): string;
+/**
+ * Resolves a path relative to the provided module's directory.
+ *
+ * @remarks
+ * Useful for loading internal assets such as:
+ * - `.hbs` templates
+ * - JSON files
+ * - SQL schemas
+ * - bundled static resources
+ *
+ * Unlike `process.cwd()`, this resolves relative to the module
+ * file location, making it safe for usage inside `node_modules`.
+ *
+ * @returns Absolute resolved path.
+ *
+ * @throws {Error}
+ * If module path is not provided.
+ *
+ * @example ESM
+ * ```ts
+ * const templatePath = resolveModuleRelative(
+ *   "../templates/welcome.hbs",
+ *   import.meta.url
+ * );
+ * ```
+ *
+ * @example CommonJS
+ * ```ts
+ * const templatePath = resolveModuleRelative(
+ *   "../templates/welcome.hbs",
+ *   __filename
+ * );
+ * ```
+ */
+declare function resolveModuleRelative(/** Path relative to the module directory */relativePath: string, /** `import.meta.url` (ESM) or `__filename` (CJS) */metaUrlOrPath: string): string;
+//#endregion
+//#region src/path.d.ts
+/**
+ * Converts a file system path to POSIX format.
+ *
+ * @remarks
+ * - Replaces all backslashes (`\`) with forward slashes (`/`).
+ * - Does NOT perform full path normalization (e.g., resolving `.` or `..` segments).
+ *
+ * @returns The path using POSIX separators (`/`).
+ *
+ * @example
+ * ```ts
+ * toPosixPath('C:\\Users\\TenE\\project')
+ * // => 'C:/Users/TenE/project'
+ * ```
+ *
+ * @example
+ * ```ts
+ * toPosixPath('src\\utils\\file.ts')
+ * // => 'src/utils/file.ts'
+ * ```
+ */
+declare function toPosixPath(/** The path to convert */
+
+p: string): string;
+/**
+ * Converts a file system path to Windows (Win32) format.
+ *
+ * On POSIX systems (Linux/macOS), all forward slashes (`/`) are replaced with backslashes (`\`).
+ *
+ * @returns The path using Windows separators (`\`).
+ *
+ * @example
+ * ```ts
+ * toWinPath('src/utils/file.ts')
+ * // => 'src\\utils\\file.ts'
+ * ```
+ *
+ * @example
+ * ```ts
+ * toWinPath('/usr/local/bin')
+ * // => '\\usr\\local\\bin'
+ * ```
+ */
+declare function toWinPath(/** The path to convert */
+
+p: string): string;
+/**
+ * Converts a file system path to the current platform-specific format.
+ *
+ * This replaces both forward slashes (`/`) and backslashes (`\`) with the platform's separator (`path.sep`).
+ *
+ * - Windows → `\`
+ * - macOS/Linux → `/`
+ *
+ * @returns The path using the current OS separator.
+ *
+ * @example Mixed Separators
+ * ```ts
+ * toPlatformPath('src/utils/file.ts')
+ * // On Windows: 'src\\utils\\file.ts'
+ * // On POSIX:   'src/utils/file.ts'
+ * ```
+ */
+declare function toPlatformPath(/** The path to convert */
+
+p: string): string;
+//#endregion
+export { createArchive, hasCommonJSFilename, locateModuleDirectory, locateModuleFile, resolveModuleRelative, toPlatformPath, toPosixPath, toWinPath };

package/dist/index.mjs

@@ -1 +1 @@
-import e from"fs";import t from"path";import n from"archiver";function r({format:r,source:i,destination:a,options:o={},log:s=!0,onSuccess:c}){let l=t.resolve(i);if(!e.existsSync(l)||!e.statSync(l).isDirectory())throw Error(`Source directory "${i}" does not exist or is not a directory.`);let u=e.createWriteStream(a);r===`zip`&&(o={...o,zlib:{level:9}});let d=n(r,o);return new Promise((e,t)=>{u.on(`close`,()=>{let t=d.pointer();s&&console.log(`${a} created: ${t} total bytes`),c&&c(t),e()}),d.on(`error`,e=>{t(e)}),d.pipe(u),d.directory(i,!1),d.finalize().catch(e=>t(e instanceof Error?e:Error(String(e))))})}export{r as createArchive};
+import e from"fs";import t from"path";import n from"archiver";import{fileURLToPath as r}from"url";function i({format:r,source:i,destination:a,options:o={},log:s=!0,onSuccess:c}){let l=t.resolve(i);if(!e.existsSync(l)||!e.statSync(l).isDirectory())throw Error(`Source directory "${i}" does not exist or is not a directory.`);let u=e.createWriteStream(a);r===`zip`&&(o={...o,zlib:{level:9}});let d=n(r,o);return new Promise((e,t)=>{u.on(`close`,()=>{let t=d.pointer();s&&console.log(`${a} created: ${t} total bytes`),c&&c(t),e()}),d.on(`error`,e=>{t(e)}),d.pipe(u),d.directory(i,!1),d.finalize().catch(e=>t(e instanceof Error?e:Error(String(e))))})}const a=typeof __filename<`u`;function o(e){if(!e)throw Error(`locateModuleFile requires import.meta.url (ESM) or __filename (CJS).`);return e.startsWith(`file:`)?r(e):e}function s(e){return t.dirname(o(e))}function c(e,n){let r=s(n),i=t.resolve(r,e);if(t.relative(r,i).startsWith(`..`))throw Error(`Resolved path escapes module directory.`);return i}function l(e){return e.replace(/\\/g,`/`)}function u(e){return e.replace(/\//g,`\\`)}function d(e){return e.replace(/[/\\]/g,t.sep)}export{i as createArchive,a as hasCommonJSFilename,s as locateModuleDirectory,o as locateModuleFile,c as resolveModuleRelative,d as toPlatformPath,l as toPosixPath,u as toWinPath};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@js-utils-kit/fs",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "File system utilities",
   "private": false,
   "license": "MIT",
@@ -30,13 +30,13 @@
   "types": "./dist/index.d.cts",
   "exports": {
     ".": {
-      "require": "./dist/index.cjs",
-      "import": "./dist/index.mjs"
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
     }
   },
   "dependencies": {
     "archiver": "^7.0.1",
-    "@js-utils-kit/types": "1.2.0"
+    "@js-utils-kit/types": "1.3.0"
   },
   "scripts": {
     "build": "tsdown",