tiny-essentials 1.28.19 → 1.29.1

package/dist/v1/libs/fs/path.cjs

@@ -0,0 +1,234 @@
+'use strict';
+
+var constants = require('./constants.cjs');
+
+/**
+ * @file Pure POSIX-like path helpers.
+ *
+ * OPFS has no symbolic links, therefore `.` and `..` can be resolved
+ * lexically without touching the file system.
+ *
+ * @remarks
+ * The public API mirrors `node:path` from the Node.js project, used here
+ * as the reference specification. Node.js is distributed under the MIT
+ * license.
+ *
+ * @see {@link https://nodejs.org/api/path.html}
+ */
+
+
+/**
+ * @typedef {Object} ParsedPath
+ * @property {string} root Root of the path. Always `/`.
+ * @property {string} dir Directory of the path.
+ * @property {string} base Base name, including the extension.
+ * @property {string} ext Extension, including the leading dot.
+ * @property {string} name Base name, without the extension.
+ */
+
+/**
+ * @typedef {Object} PathObject
+ * @property {string} [root] Root of the path.
+ * @property {string} [dir] Directory of the path.
+ * @property {string} [base] Base name, including the extension.
+ * @property {string} [ext] Extension, including the leading dot.
+ * @property {string} [name] Base name, without the extension.
+ */
+
+/**
+ * Platform-specific path segment separator. Always `/` in the browser.
+ *
+ * @type {string}
+ */
+const sep = constants.PATH_SEPARATOR;
+
+/**
+ * Platform-specific list separator, as used by `PATH`-like variables.
+ *
+ * @type {string}
+ */
+const delimiter = ':';
+
+/**
+ * Splits a POSIX-like path into normalised segments.
+ *
+ * @param {string} targetPath Path to normalise.
+ * @returns {string[]} The normalised segments, without empty entries.
+ */
+const toSegments = (targetPath) => {
+  /** @type {string[]} */
+  const segments = [];
+  for (const segment of targetPath.split(constants.PATH_SEPARATOR)) {
+    if (segment.length === 0 || segment === '.') {
+      continue;
+    }
+    if (segment === '..') {
+      segments.pop();
+      continue;
+    }
+    segments.push(segment);
+  }
+  return segments;
+};
+
+/**
+ * Rebuilds an absolute path from normalised segments.
+ *
+ * @param {string[]} segments Normalised segments.
+ * @returns {string} An absolute path starting with `/`.
+ */
+const toAbsolutePath = (segments) => constants.PATH_SEPARATOR + segments.join(constants.PATH_SEPARATOR);
+
+/**
+ * Normalises a path.
+ *
+ * @param {string} targetPath Path to normalise.
+ * @returns {string} The normalised absolute path.
+ */
+const normalize = (targetPath) => toAbsolutePath(toSegments(targetPath));
+
+/**
+ * Joins path fragments and normalises the result.
+ *
+ * @param {string[]} parts Path fragments.
+ * @returns {string} The joined absolute path.
+ */
+const join = (...parts) => normalize(parts.join(constants.PATH_SEPARATOR));
+
+/**
+ * Returns the parent directory of a path.
+ *
+ * @param {string} targetPath Source path.
+ * @returns {string} The parent directory.
+ */
+const dirname = (targetPath) => {
+  const segments = toSegments(targetPath);
+  segments.pop();
+  return toAbsolutePath(segments);
+};
+
+/**
+ * Returns the last segment of a path.
+ *
+ * @param {string} targetPath Source path.
+ * @param {string} [extension] Extension removed from the result.
+ * @returns {string} The base name.
+ */
+const basename = (targetPath, extension) => {
+  const segments = toSegments(targetPath);
+  const name = segments.at(-1) ?? '';
+  if (extension !== undefined && name.endsWith(extension)) {
+    return name.slice(0, name.length - extension.length);
+  }
+  return name;
+};
+
+/**
+ * Returns the extension of a path, including the leading dot.
+ *
+ * @param {string} targetPath Source path.
+ * @returns {string} The extension, or an empty string.
+ */
+const extname = (targetPath) => {
+  const name = basename(targetPath);
+  const index = name.lastIndexOf('.');
+  return index <= 0 ? '' : name.slice(index);
+};
+
+/**
+ * Reports whether a path is absolute.
+ *
+ * @param {string} targetPath Source path.
+ * @returns {boolean} `true` when the path starts with a slash.
+ */
+const isAbsolute = (targetPath) => targetPath.startsWith(constants.PATH_SEPARATOR);
+
+/**
+ * Resolves a sequence of path fragments against a working directory.
+ *
+ * @param {string} cwd Working directory used for relative fragments.
+ * @param {string[]} parts Path fragments.
+ * @returns {string} The resolved absolute path.
+ */
+const resolve = (cwd, ...parts) => {
+  const [first, ...rest] = parts;
+  if (first === undefined) {
+    return normalize(cwd);
+  }
+  const base = isAbsolute(first) ? first : `${cwd}${constants.PATH_SEPARATOR}${first}`;
+  return resolve(base, ...rest);
+};
+
+/**
+ * Parses a path into its structural components.
+ *
+ * @param {string} targetPath Source path.
+ * @returns {ParsedPath} The parsed components.
+ */
+const parse = (targetPath) => {
+  const segments = toSegments(targetPath);
+  const base = segments.at(-1) ?? '';
+  const extension = extname(base);
+  return {
+    root: constants.PATH_SEPARATOR,
+    dir: toAbsolutePath(segments.slice(0, -1)),
+    base,
+    ext: extension,
+    name: extension.length === 0 ? base : base.slice(0, base.length - extension.length),
+  };
+};
+
+/**
+ * Builds a path from its structural components.
+ *
+ * @param {PathObject} pathObject Components to serialise.
+ * @returns {string} The normalised absolute path.
+ * @throws {TypeError} When `pathObject` is not a plain object.
+ */
+const format = (pathObject) => {
+  if (pathObject === null || typeof pathObject !== 'object' || Array.isArray(pathObject)) {
+    throw new TypeError('The "pathObject" argument must be of type object');
+  }
+  const { root, dir, base, ext, name } = pathObject;
+  const resolvedBase = base ?? `${name ?? ''}${ext ?? ''}`;
+  const resolvedDirectory = dir ?? root ?? constants.ROOT_PATH;
+  return normalize(`${resolvedDirectory}${constants.PATH_SEPARATOR}${resolvedBase}`);
+};
+
+/**
+ * Computes the relative path from one location to another.
+ *
+ * @param {string} from Source path.
+ * @param {string} to Destination path.
+ * @returns {string} The relative path, or an empty string when both are equal.
+ */
+const relative = (from, to) => {
+  const fromSegments = toSegments(from);
+  const toSegmentsList = toSegments(to);
+  let shared = 0;
+  while (
+    shared < fromSegments.length &&
+    shared < toSegmentsList.length &&
+    fromSegments[shared] === toSegmentsList[shared]
+  ) {
+    shared += 1;
+  }
+  const upward = new Array(fromSegments.length - shared).fill('..');
+  return [...upward, ...toSegmentsList.slice(shared)].join(constants.PATH_SEPARATOR);
+};
+
+exports.ROOT_PATH = constants.ROOT_PATH;
+exports.basename = basename;
+exports.delimiter = delimiter;
+exports.dirname = dirname;
+exports.extname = extname;
+exports.format = format;
+exports.isAbsolute = isAbsolute;
+exports.join = join;
+exports.normalize = normalize;
+exports.parse = parse;
+exports.relative = relative;
+exports.resolve = resolve;
+exports.sep = sep;
+exports.toAbsolutePath = toAbsolutePath;
+exports.toSegments = toSegments;

package/dist/v1/libs/fs/path.d.mts

@@ -0,0 +1,176 @@
+/**
+ * @file Pure POSIX-like path helpers.
+ *
+ * OPFS has no symbolic links, therefore `.` and `..` can be resolved
+ * lexically without touching the file system.
+ *
+ * @remarks
+ * The public API mirrors `node:path` from the Node.js project, used here
+ * as the reference specification. Node.js is distributed under the MIT
+ * license.
+ *
+ * @see {@link https://nodejs.org/api/path.html}
+ */
+import { ROOT_PATH } from './constants.mjs';
+export type ParsedPath = {
+    /**
+     * Root of the path. Always `/`.
+     */
+    root: string;
+    /**
+     * Directory of the path.
+     */
+    dir: string;
+    /**
+     * Base name, including the extension.
+     */
+    base: string;
+    /**
+     * Extension, including the leading dot.
+     */
+    ext: string;
+    /**
+     * Base name, without the extension.
+     */
+    name: string;
+};
+export type PathObject = {
+    /**
+     * Root of the path.
+     */
+    root?: string;
+    /**
+     * Directory of the path.
+     */
+    dir?: string;
+    /**
+     * Base name, including the extension.
+     */
+    base?: string;
+    /**
+     * Extension, including the leading dot.
+     */
+    ext?: string;
+    /**
+     * Base name, without the extension.
+     */
+    name?: string;
+};
+/**
+ * @typedef {Object} ParsedPath
+ * @property {string} root Root of the path. Always `/`.
+ * @property {string} dir Directory of the path.
+ * @property {string} base Base name, including the extension.
+ * @property {string} ext Extension, including the leading dot.
+ * @property {string} name Base name, without the extension.
+ */
+/**
+ * @typedef {Object} PathObject
+ * @property {string} [root] Root of the path.
+ * @property {string} [dir] Directory of the path.
+ * @property {string} [base] Base name, including the extension.
+ * @property {string} [ext] Extension, including the leading dot.
+ * @property {string} [name] Base name, without the extension.
+ */
+/**
+ * Platform-specific path segment separator. Always `/` in the browser.
+ *
+ * @type {string}
+ */
+export declare const sep: string;
+/**
+ * Platform-specific list separator, as used by `PATH`-like variables.
+ *
+ * @type {string}
+ */
+export declare const delimiter: string;
+/**
+ * Splits a POSIX-like path into normalised segments.
+ *
+ * @param {string} targetPath Path to normalise.
+ * @returns {string[]} The normalised segments, without empty entries.
+ */
+export declare const toSegments: (targetPath: string) => string[];
+/**
+ * Rebuilds an absolute path from normalised segments.
+ *
+ * @param {string[]} segments Normalised segments.
+ * @returns {string} An absolute path starting with `/`.
+ */
+export declare const toAbsolutePath: (segments: string[]) => string;
+/**
+ * Normalises a path.
+ *
+ * @param {string} targetPath Path to normalise.
+ * @returns {string} The normalised absolute path.
+ */
+export declare const normalize: (targetPath: string) => string;
+/**
+ * Joins path fragments and normalises the result.
+ *
+ * @param {string[]} parts Path fragments.
+ * @returns {string} The joined absolute path.
+ */
+export declare const join: (...parts: string[]) => string;
+/**
+ * Returns the parent directory of a path.
+ *
+ * @param {string} targetPath Source path.
+ * @returns {string} The parent directory.
+ */
+export declare const dirname: (targetPath: string) => string;
+/**
+ * Returns the last segment of a path.
+ *
+ * @param {string} targetPath Source path.
+ * @param {string} [extension] Extension removed from the result.
+ * @returns {string} The base name.
+ */
+export declare const basename: (targetPath: string, extension?: string) => string;
+/**
+ * Returns the extension of a path, including the leading dot.
+ *
+ * @param {string} targetPath Source path.
+ * @returns {string} The extension, or an empty string.
+ */
+export declare const extname: (targetPath: string) => string;
+/**
+ * Reports whether a path is absolute.
+ *
+ * @param {string} targetPath Source path.
+ * @returns {boolean} `true` when the path starts with a slash.
+ */
+export declare const isAbsolute: (targetPath: string) => boolean;
+/**
+ * Resolves a sequence of path fragments against a working directory.
+ *
+ * @param {string} cwd Working directory used for relative fragments.
+ * @param {string[]} parts Path fragments.
+ * @returns {string} The resolved absolute path.
+ */
+export declare const resolve: (cwd: string, ...parts: string[]) => string;
+/**
+ * Parses a path into its structural components.
+ *
+ * @param {string} targetPath Source path.
+ * @returns {ParsedPath} The parsed components.
+ */
+export declare const parse: (targetPath: string) => ParsedPath;
+/**
+ * Builds a path from its structural components.
+ *
+ * @param {PathObject} pathObject Components to serialise.
+ * @returns {string} The normalised absolute path.
+ * @throws {TypeError} When `pathObject` is not a plain object.
+ */
+export declare const format: (pathObject: PathObject) => string;
+/**
+ * Computes the relative path from one location to another.
+ *
+ * @param {string} from Source path.
+ * @param {string} to Destination path.
+ * @returns {string} The relative path, or an empty string when both are equal.
+ */
+export declare const relative: (from: string, to: string) => string;
+export { ROOT_PATH };
+//# sourceMappingURL=path.d.mts.map

package/dist/v1/libs/fs/path.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.mts","sourceRoot":"","sources":["../../../../src/v1/libs/fs/path.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAkB,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGzD,YAAkB,UAAU,GAC5B;;;;IAAmB,IAAI,EAAZ,MAAM,CACjB;;;;IAAmB,GAAG,EAAX,MAAM,CACjB;;;;IAAmB,IAAI,EAAZ,MAAM,CACjB;;;;IAAmB,GAAG,EAAX,MAAM,CACjB;;;;IAAmB,IAAI,EAAZ,MAAM,CACnB;CAAA,CAAA;AAGE,YAAkB,UAAU,GAC5B;;;;IAAoB,IAAI,AAAxB,CACA,EADW,MAAM,CACjB;;;;IAAoB,GAAG,AAAvB,CACA,EADW,MAAM,CACjB;;;;IAAoB,IAAI,AAAxB,CACA,EADW,MAAM,CACjB;;;;IAAoB,GAAG,AAAvB,CACA,EADW,MAAM,CACjB;;;;IAAoB,IAAI,AAAxB,CACF,EADa,MAAM,CACnB;CAAA,CAAA;AAhBD;;;;;;;GAOG;AAEH;;;;;;;GAOG;AAEH;;;;GAIG;AACH,eAAO,MAAM,GAAG,EAFN,MAEuB,CAAC;AAElC;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAFZ,MAEkB,CAAC;AAE7B;;;;;GAKG;AACH,eAAO,MAAM,UAAU,eAHZ,MAAM,KACJ,MAAM,EAgBlB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,aAHhB,MAAM,EAAE,KACN,MAE6E,CAAC;AAE3F;;;;;GAKG;AACH,eAAO,MAAM,SAAS,eAHX,MAAM,KACJ,MAEkE,CAAC;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,IAAI,aAHN,MAAM,EAAE,KACN,MAE0D,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,OAAO,eAHT,MAAM,KACJ,MAMZ,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,eAJV,MAAM,cACN,MAAM,KACJ,MASZ,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,eAHT,MAAM,KACJ,MAMZ,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,eAHZ,MAAM,KACJ,OAEkE,CAAC;AAEhF;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,QAJT,MAAM,YACN,MAAM,EAAE,KACN,MASZ,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,KAAK,eAHP,MAAM,KACJ,UAaZ,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,eAJR,UAAU,KACR,MAWZ,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,SAJV,MAAM,MACN,MAAM,KACJ,MAeZ,CAAC;AAEF,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/v1/libs/fs/path.mjs

@@ -0,0 +1,197 @@
+/**
+ * @file Pure POSIX-like path helpers.
+ *
+ * OPFS has no symbolic links, therefore `.` and `..` can be resolved
+ * lexically without touching the file system.
+ *
+ * @remarks
+ * The public API mirrors `node:path` from the Node.js project, used here
+ * as the reference specification. Node.js is distributed under the MIT
+ * license.
+ *
+ * @see {@link https://nodejs.org/api/path.html}
+ */
+import { PATH_SEPARATOR, ROOT_PATH } from './constants.mjs';
+/**
+ * @typedef {Object} ParsedPath
+ * @property {string} root Root of the path. Always `/`.
+ * @property {string} dir Directory of the path.
+ * @property {string} base Base name, including the extension.
+ * @property {string} ext Extension, including the leading dot.
+ * @property {string} name Base name, without the extension.
+ */
+/**
+ * @typedef {Object} PathObject
+ * @property {string} [root] Root of the path.
+ * @property {string} [dir] Directory of the path.
+ * @property {string} [base] Base name, including the extension.
+ * @property {string} [ext] Extension, including the leading dot.
+ * @property {string} [name] Base name, without the extension.
+ */
+/**
+ * Platform-specific path segment separator. Always `/` in the browser.
+ *
+ * @type {string}
+ */
+export const sep = PATH_SEPARATOR;
+/**
+ * Platform-specific list separator, as used by `PATH`-like variables.
+ *
+ * @type {string}
+ */
+export const delimiter = ':';
+/**
+ * Splits a POSIX-like path into normalised segments.
+ *
+ * @param {string} targetPath Path to normalise.
+ * @returns {string[]} The normalised segments, without empty entries.
+ */
+export const toSegments = (targetPath) => {
+    /** @type {string[]} */
+    const segments = [];
+    for (const segment of targetPath.split(PATH_SEPARATOR)) {
+        if (segment.length === 0 || segment === '.') {
+            continue;
+        }
+        if (segment === '..') {
+            segments.pop();
+            continue;
+        }
+        segments.push(segment);
+    }
+    return segments;
+};
+/**
+ * Rebuilds an absolute path from normalised segments.
+ *
+ * @param {string[]} segments Normalised segments.
+ * @returns {string} An absolute path starting with `/`.
+ */
+export const toAbsolutePath = (segments) => PATH_SEPARATOR + segments.join(PATH_SEPARATOR);
+/**
+ * Normalises a path.
+ *
+ * @param {string} targetPath Path to normalise.
+ * @returns {string} The normalised absolute path.
+ */
+export const normalize = (targetPath) => toAbsolutePath(toSegments(targetPath));
+/**
+ * Joins path fragments and normalises the result.
+ *
+ * @param {string[]} parts Path fragments.
+ * @returns {string} The joined absolute path.
+ */
+export const join = (...parts) => normalize(parts.join(PATH_SEPARATOR));
+/**
+ * Returns the parent directory of a path.
+ *
+ * @param {string} targetPath Source path.
+ * @returns {string} The parent directory.
+ */
+export const dirname = (targetPath) => {
+    const segments = toSegments(targetPath);
+    segments.pop();
+    return toAbsolutePath(segments);
+};
+/**
+ * Returns the last segment of a path.
+ *
+ * @param {string} targetPath Source path.
+ * @param {string} [extension] Extension removed from the result.
+ * @returns {string} The base name.
+ */
+export const basename = (targetPath, extension) => {
+    const segments = toSegments(targetPath);
+    const name = segments.at(-1) ?? '';
+    if (extension !== undefined && name.endsWith(extension)) {
+        return name.slice(0, name.length - extension.length);
+    }
+    return name;
+};
+/**
+ * Returns the extension of a path, including the leading dot.
+ *
+ * @param {string} targetPath Source path.
+ * @returns {string} The extension, or an empty string.
+ */
+export const extname = (targetPath) => {
+    const name = basename(targetPath);
+    const index = name.lastIndexOf('.');
+    return index <= 0 ? '' : name.slice(index);
+};
+/**
+ * Reports whether a path is absolute.
+ *
+ * @param {string} targetPath Source path.
+ * @returns {boolean} `true` when the path starts with a slash.
+ */
+export const isAbsolute = (targetPath) => targetPath.startsWith(PATH_SEPARATOR);
+/**
+ * Resolves a sequence of path fragments against a working directory.
+ *
+ * @param {string} cwd Working directory used for relative fragments.
+ * @param {string[]} parts Path fragments.
+ * @returns {string} The resolved absolute path.
+ */
+export const resolve = (cwd, ...parts) => {
+    const [first, ...rest] = parts;
+    if (first === undefined) {
+        return normalize(cwd);
+    }
+    const base = isAbsolute(first) ? first : `${cwd}${PATH_SEPARATOR}${first}`;
+    return resolve(base, ...rest);
+};
+/**
+ * Parses a path into its structural components.
+ *
+ * @param {string} targetPath Source path.
+ * @returns {ParsedPath} The parsed components.
+ */
+export const parse = (targetPath) => {
+    const segments = toSegments(targetPath);
+    const base = segments.at(-1) ?? '';
+    const extension = extname(base);
+    return {
+        root: PATH_SEPARATOR,
+        dir: toAbsolutePath(segments.slice(0, -1)),
+        base,
+        ext: extension,
+        name: extension.length === 0 ? base : base.slice(0, base.length - extension.length),
+    };
+};
+/**
+ * Builds a path from its structural components.
+ *
+ * @param {PathObject} pathObject Components to serialise.
+ * @returns {string} The normalised absolute path.
+ * @throws {TypeError} When `pathObject` is not a plain object.
+ */
+export const format = (pathObject) => {
+    if (pathObject === null || typeof pathObject !== 'object' || Array.isArray(pathObject)) {
+        throw new TypeError('The "pathObject" argument must be of type object');
+    }
+    const { root, dir, base, ext, name } = pathObject;
+    const resolvedBase = base ?? `${name ?? ''}${ext ?? ''}`;
+    const resolvedDirectory = dir ?? root ?? ROOT_PATH;
+    return normalize(`${resolvedDirectory}${PATH_SEPARATOR}${resolvedBase}`);
+};
+/**
+ * Computes the relative path from one location to another.
+ *
+ * @param {string} from Source path.
+ * @param {string} to Destination path.
+ * @returns {string} The relative path, or an empty string when both are equal.
+ */
+export const relative = (from, to) => {
+    const fromSegments = toSegments(from);
+    const toSegmentsList = toSegments(to);
+    let shared = 0;
+    while (shared < fromSegments.length &&
+        shared < toSegmentsList.length &&
+        fromSegments[shared] === toSegmentsList[shared]) {
+        shared += 1;
+    }
+    const upward = new Array(fromSegments.length - shared).fill('..');
+    return [...upward, ...toSegmentsList.slice(shared)].join(PATH_SEPARATOR);
+};
+export { ROOT_PATH };