@gesslar/toolkit 3.22.2 → 3.24.0

package/src/node/lib/FileObject.js

@@ -6,9 +6,9 @@
 
 import JSON5 from "json5"
 import fs from "node:fs/promises"
-import path from "node:path"
 import YAML from "yaml"
 import {URL} from "node:url"
+import {Buffer} from "node:buffer"
 
 import Data from "../../browser/lib/Data.js"
 import DirectoryObject from "./DirectoryObject.js"
@@ -47,7 +47,6 @@ export default class FileObject extends FS {
 
   /**
    * @type {object}
-   * @private
    * @property {string|null} supplied - User-supplied path
    * @property {string|null} path - The absolute file path
    * @property {URL|null} url - The file URL
@@ -67,26 +66,9 @@ export default class FileObject extends FS {
     isFile: true,
     parent: null,
     parentPath: null,
+    real: null,
   })
 
-  /**
-   * Strip root from absolute path to make it relative.
-   * Used for virtual filesystem path resolution.
-   *
-   * @private
-   * @static
-   * @param {string} pathName - The path to convert
-   * @returns {string} Path with root stripped, or original if already relative
-   */
-  static #absoluteToRelative(pathName) {
-    if(!path.isAbsolute(pathName))
-      return pathName
-
-    const {root} = FS.pathParts(pathName)
-
-    return Data.chopLeft(pathName, root)
-  }
-
   /**
    * Constructs a FileObject instance.
    *
@@ -100,14 +82,15 @@ export default class FileObject extends FS {
     Valid.type(parent, "Null|String|DirectoryObject", {allowEmpty: false})
 
     const normalizedFile = FS.fixSlashes(submitted)
-    const absOrRelPath = path.isAbsolute(normalizedFile) && parent
-      ? FileObject.#absoluteToRelative(normalizedFile)
-      : normalizedFile
-    const {dir, base, ext, name} = FS.pathParts(absOrRelPath)
+    const absOrRelPath = normalizedFile
+    const pathParts = FS.pathParts(absOrRelPath)
+    const {dir, base, ext} = pathParts
+    const name = base.slice(0, base.length - ext.length)
 
     const [parentObject, fullPath] = (() => {
       if(Data.isType(parent, "String")) {
-        const resolved = FS.resolvePath(parent, absOrRelPath)
+        const parentPath = /** @type {string} */ (parent)
+        const resolved = FS.resolvePath(parentPath, absOrRelPath)
         const {dir} = FS.pathParts(resolved)
 
         return [
@@ -116,15 +99,16 @@ export default class FileObject extends FS {
         ]
       }
 
-      if(Data.isType(parent, "DirectoryObject")) {
-        const parentPath = parent.path
+      if(Data.isType(parent, "DirectoryObject") && parent !== null) {
+        const parentDir = /** @type {DirectoryObject} */ (parent)
+        const parentPath = parentDir.path
         const resolved = FS.resolvePath(parentPath, absOrRelPath)
         const parts = FS.pathParts(resolved)
 
         return [
-          parent.path === parts.dir
-            ? parent
-            : new parent.constructor(parts.dir, parent),
+          parentDir.path === parts.dir
+            ? parentDir
+            : new DirectoryObject(parts.dir),
           resolved,
         ]
       }
@@ -160,9 +144,7 @@ export default class FileObject extends FS {
    * @returns {string} String representation of the FileObject
    */
   toString() {
-    return this.isVirtual
-      ?`[${this.constructor.name}: ${this.path} → ${this.real.path}]`
-      :`[${this.constructor.name}: ${this.path}]`
+    return `[${this.constructor.name}: ${this.path}]`
   }
 
   /**
@@ -271,7 +253,7 @@ export default class FileObject extends FS {
    */
   async canRead() {
     try {
-      await fs.access(this.real?.path ?? this.path, fs.constants.R_OK)
+      await fs.access(this.path, fs.constants.R_OK)
 
       return true
     } catch {
@@ -286,7 +268,7 @@ export default class FileObject extends FS {
    */
   async canWrite() {
     try {
-      await fs.access(this.real?.path ?? this.path, fs.constants.W_OK)
+      await fs.access(this.path, fs.constants.W_OK)
 
       return true
     } catch {
@@ -301,7 +283,7 @@ export default class FileObject extends FS {
    */
   async #fileExists() {
     try {
-      await fs.access(this.real?.path ?? this.path, fs.constants.F_OK)
+      await fs.access(this.path, fs.constants.F_OK)
 
       return true
     } catch {
@@ -316,7 +298,7 @@ export default class FileObject extends FS {
    */
   async size() {
     try {
-      const stat = await fs.stat(this.real?.path ?? this.path)
+      const stat = await fs.stat(this.path)
 
       return stat.size
     } catch {
@@ -332,7 +314,7 @@ export default class FileObject extends FS {
    */
   async modified() {
     try {
-      const stat = await fs.stat(this.real?.path ?? this.path)
+      const stat = await fs.stat(this.path)
 
       return stat.mtime
     } catch {
@@ -347,7 +329,7 @@ export default class FileObject extends FS {
    * @returns {Promise<string>} The file contents
    */
   async read(encoding="utf8") {
-    const filePath = this.real?.path ?? this.path
+    const filePath = this.path
 
     if(!(await this.exists))
       throw Sass.new(`No such file '${filePath}'`)
@@ -368,7 +350,7 @@ export default class FileObject extends FS {
    * // Use the buffer (e.g., send in HTTP response, process image, etc.)
    */
   async readBinary() {
-    const filePath = this.real?.path ?? this.path
+    const filePath = this.path
 
     if(!(await this.exists))
       throw Sass.new(`No such file '${filePath}'`)
@@ -389,7 +371,7 @@ export default class FileObject extends FS {
    * await file.write(JSON.stringify({key: 'value'}))
    */
   async write(content, encoding="utf8") {
-    const filePath = this.real?.path ?? this.path
+    const filePath = this.path
 
     if(!filePath)
       throw Sass.new("No actual disk location detected.")
@@ -418,7 +400,7 @@ export default class FileObject extends FS {
    * await file.writeBinary(buffer)
    */
   async writeBinary(data) {
-    const filePath = this.real?.path ?? this.path
+    const filePath = this.path
 
     const exists = await this.parent.exists
     Valid.assert(exists, `Invalid directory writing ${filePath}`)
@@ -480,7 +462,7 @@ export default class FileObject extends FS {
    * @returns {Promise<object>} The file contents as a module.
    */
   async import() {
-    const filePath = this.real?.path ?? this.path
+    const filePath = this.path
 
     if(!(await this.exists))
       throw Sass.new(`No such file '${filePath}'`)
@@ -499,11 +481,56 @@ export default class FileObject extends FS {
    * await file.delete()
    */
   async delete() {
-    const filePath = this.real?.path ?? this.path
+    const filePath = this.path
 
     if(!(await this.exists))
       throw Sass.new(`No such resource '${filePath}'`)
 
     return await fs.unlink(filePath)
   }
+
+  /**
+   * Creates a FileObject representing the current working file (the file
+   * that called this method). Parses the stack trace to determine the
+   * caller's file path.
+   *
+   * @returns {FileObject} A new FileObject instance for the calling file
+   * @throws {Sass} If unable to determine caller file from stack trace
+   * @example
+   * // In /home/user/project/src/app.js:
+   * const thisFile = FileObject.fromCwf()
+   * console.log(thisFile.path) // /home/user/project/src/app.js
+   */
+  static fromCwf() {
+    const originalPrepare = Error.prepareStackTrace
+    Error.prepareStackTrace = (_, stack) => stack
+    /** @type {Array<{getFileName: () => string|null}>} */
+    const stack = (new Error().stack)
+    Error.prepareStackTrace = originalPrepare
+
+    // Find the first call site that isn't this file
+    // Stack filenames may be file:// URLs, so compare both forms
+    const thisFileUrl = import.meta.url
+    const thisFilePath = FS.urlToPath(thisFileUrl)
+    const callerSite = stack.find(site => {
+      const fileName = site.getFileName()
+
+      if(!fileName)
+        return false
+
+      return fileName !== thisFileUrl && fileName !== thisFilePath
+    })
+
+    const callerFile = callerSite?.getFileName()
+
+    if(!callerFile)
+      throw Sass.new("Unable to determine caller file from stack trace")
+
+    // Handle file:// URLs
+    const filePath = callerFile.startsWith("file://")
+      ? FS.urlToPath(callerFile)
+      : callerFile
+
+    return new this(filePath)
+  }
 }

package/src/node/lib/FileSystem.js

@@ -14,6 +14,7 @@ import url from "node:url"
 import Collection from "../../browser/lib/Collection.js"
 import Data from "../../browser/lib/Data.js"
 import Valid from "./Valid.js"
+import Sass from "./Sass.js"
 
 /** @typedef {import("./FileObject.js").default} FileObject */
 /** @typedef {import("./DirectoryObject.js").default} DirectoryObject */
@@ -79,17 +80,19 @@ export default class FileSystem {
   }
 
   /**
-   * Convert a URI to a path
+   * Convert a file URL to a path.
    *
    * @static
-   * @param {string} pathName - The URI to convert
-   * @returns {string} The path
+   * @param {string} fileUrl - The file URL to convert (e.g., import.meta.url)
+   * @returns {string} The file path
+   * @example
+   * const currentFile = FileSystem.urlToPath(import.meta.url)
    */
-  static urlToPath(pathName) {
+  static urlToPath(fileUrl) {
     try {
-      return url.fileURLToPath(new URL(pathName).pathName)
+      return url.fileURLToPath(fileUrl)
     } catch {
-      return pathName
+      return fileUrl
     }
   }
 
@@ -318,6 +321,8 @@ export default class FileSystem {
    * @property {string} base - The file name with extension
    * @property {string} dir - The directory path
    * @property {string} ext - The file extension (including dot)
+   * @property {string} root - The root of the path
+   * @property {string} name - The file name without extension
    */
 
   /**
@@ -334,48 +339,6 @@ export default class FileSystem {
     return path.parse(pathName)
   }
 
-  /**
-   * Convert a virtual capped path to its real filesystem path.
-   * For capped objects, resolves the virtual path relative to the cap's real path.
-   * For uncapped objects, returns the path unchanged.
-   *
-   * @static
-   * @param {FileObject|DirectoryObject} fileOrDirectoryObject - The file or directory object to convert
-   * @returns {string} The real filesystem path
-   * @throws {Sass} If parameter is not a FileObject or DirectoryObject
-   * @example
-   * const temp = new TempDirectoryObject("myapp")
-   * const file = temp.getFile("/config.json")
-   * FS.virtualToRealPath(file) // "/tmp/myapp-ABC123/config.json"
-   *
-   * @example
-   * const regular = new FileObject("/home/user/file.txt")
-   * FS.virtualToRealPath(regular) // "/home/user/file.txt"
-   */
-  static virtualToRealPath(fileOrDirectoryObject) {
-    Valid.type(fileOrDirectoryObject, "FileObject|DirectoryObject")
-
-    let target, cap
-
-    if(fileOrDirectoryObject.isFile) {
-      if(!fileOrDirectoryObject.parent.isVirtual) {
-        return fileOrDirectoryObject.path
-      } else {
-        target = fileOrDirectoryObject.path
-        cap = fileOrDirectoryObject.parent.cap.real.path
-      }
-    } else {
-      if(!fileOrDirectoryObject.isVirtual) {
-        return fileOrDirectoryObject.path
-      } else {
-        target = fileOrDirectoryObject.path
-        cap = fileOrDirectoryObject.cap.real.path
-      }
-    }
-
-    return this.resolvePath(cap, target)
-  }
-
   /**
    * Returns the current working directory as a string.
    *

package/src/node/lib/Glog.js

@@ -542,17 +542,6 @@ class Glog {
       : c`${namePrefix}${colours[level]}${tag}{/} ${message}`
   }
 
-  /**
-   * Extract file and function information from stack trace
-   *
-   * @private
-   * @returns {string} Caller tag
-   */
-  extractFileFunction() {
-    // Simple fallback - just return a basic tag
-    return "caller"
-  }
-
   /**
    * Create a new debug function with a specific tag
    *
@@ -562,7 +551,8 @@ class Glog {
   newDebug(tag) {
     return function(message, level, ...arg) {
       if(this.#stackTrace || Glog.stackTrace) {
-        tag = this.extractFileFunction()
+        // extractFileFunction was removed - use original tag as fallback
+        // Stack trace extraction is not available in Glog (use Logger for full stack trace support)
       }
 
       this.debug(`[${tag}] ${message}`, level, ...arg)

package/src/node/lib/Valid.js

@@ -9,6 +9,13 @@ import Sass from "./Sass.js"
 import Data from "../../browser/lib/Data.js"
 import Collection from "../../browser/lib/Collection.js"
 
+/**
+ * Options for type validation methods.
+ *
+ * @typedef {object} TypeValidationOptions
+ * @property {boolean} [allowEmpty=true] - Whether empty values are allowed
+ */
+
 /**
  * Validation utility class providing type checking and assertion methods.
  */
@@ -20,7 +27,7 @@ export default class Valid {
    *
    * @param {unknown} value - The value to validate
    * @param {string} type - The expected type in the form of "object", "object[]", "object|object[]"
-   * @param {object} [options] - Additional options for validation.
+   * @param {TypeValidationOptions} [options] - Additional options for validation.
    */
   static type(value, type, options) {
     const expected = [type]

package/types/browser/lib/Data.d.ts

@@ -89,24 +89,46 @@ export default class Data {
      * @returns {string} The remaining string
      */
     static chopBefore(string: string, needle: string, caseInsensitive?: boolean): string;
+    /**
+     * Options for creating a new TypeSpec.
+     *
+     * @typedef {object} TypeSpecOptions
+     * @property {string} [delimiter="|"] - The delimiter for union types
+     */
+    /**
+     * Options for type validation methods.
+     *
+     * @typedef {object} TypeValidationOptions
+     * @property {boolean} [allowEmpty=true] - Whether empty values are allowed
+     */
     /**
      * Creates a type spec from a string. A type spec is an array of objects
      * defining the type of a value and whether an array is expected.
      *
      * @param {string} string - The string to parse into a type spec.
-     * @param {object} options - Additional options for parsing.
+     * @param {TypeSpecOptions} [options] - Additional options for parsing.
      * @returns {Array<object>} An array of type specs.
      */
-    static newTypeSpec(string: string, options: object): Array<object>;
+    static newTypeSpec(string: string, options?: {
+        /**
+         * - The delimiter for union types
+         */
+        delimiter?: string;
+    }): Array<object>;
     /**
      * Checks if a value is of a specified type
      *
      * @param {unknown} value The value to check
      * @param {string|TypeSpec} type The type to check for
-     * @param {object} options Additional options for checking
+     * @param {TypeValidationOptions} [options] Additional options for checking
      * @returns {boolean} Whether the value is of the specified type
      */
-    static isType(value: unknown, type: string | TypeSpec, options?: object): boolean;
+    static isType(value: unknown, type: string | TypeSpec, options?: {
+        /**
+         * - Whether empty values are allowed
+         */
+        allowEmpty?: boolean;
+    }): boolean;
     /**
      * Checks if a type is valid
      *

package/types/browser/lib/Data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Data.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/Data.js"],"names":[],"mappings":"AAUA;IACA;;;;;OAKG;IACD,mBAFQ,KAAK,CAAC,MAAM,CAAC,CAgBnB;IAEF;;;;;OAKG;IACH,qBAFU,KAAK,CAAC,MAAM,CAAC,CAmBrB;IAEF;;;;;;;OAOG;IACH,kBAFU,KAAK,CAAC,MAAM,CAAC,CAKrB;IAEF;;;;;OAKG;IACH,uBAFU,KAAK,CAAC,MAAM,CAAC,CAE2D;IAElF;;;;;;OAMG;IACH,sBAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAMlB;IAED;;;;;;OAMG;IACH,uBAJW,MAAM,WACN,MAAM,GACJ,MAAM,CAMlB;IAED;;;;;;;;;;;OAWG;IACH,yBATW,MAAM,UACN,MAAM,oBACN,OAAO,GACL,MAAM,CAWlB;IAED;;;;;;;;;;;OAWG;IACH,wBATW,MAAM,UACN,MAAM,oBACN,OAAO,GACL,MAAM,CAWlB;IAED;;;;;;;OAOG;IACH,yBALW,MAAM,UACN,MAAM,oBACN,OAAO,GACL,MAAM,CAWlB;IAED;;;;;;;OAOG;IACH,0BALW,MAAM,UACN,MAAM,oBACN,OAAO,GACL,MAAM,CAYlB;IAED;;;;;;;OAOG;IACH,2BAJW,MAAM,WACN,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAIzB;IAED;;;;;;;OAOG;IACH,qBALW,OAAO,QACP,MAAM,GAAC,QAAQ,YACf,MAAM,GACJ,OAAO,CAQnB;IAED;;;;;OAKG;IACH,yBAHW,MAAM,GACJ,OAAO,CASnB;IAED;;;;;;;;OAQG;IACH,yBAJW,OAAO,QACP,MAAM,GACJ,OAAO,CAwBnB;IAED;;;;;OAKG;IACH,qBAHW,OAAO,GACL,MAAM,CAclB;IAED;;;;;OAKG;IACH,wBAHW,OAAO,GACL,OAAO,CAInB;IAED;;;;;;;;OAQG;IACH,sBALW,OAAO,oBACP,OAAO,GAEL,OAAO,CA8BnB;IAED;;;;;OAKG;IACH,6BAHW,MAAM,GACJ,MAAM,CAmBlB;IAED;;;;;;;OAOG;IACH,6BAJW,MAAM,QACN,KAAK,CAAC,MAAM,CAAC,GACX,MAAM,CAiBlB;IAED;;;;;;;OAOG;IACH,2BAJW,MAAM,QACN,KAAK,CAAC,MAAM,CAAC,SACb,OAAO,QAMjB;IAED;;;;;OAKG;IACH,+BAHc,MAAM,EAAA,GACP,MAAM,CAqBlB;IAED;;;;;;;OAOG;IACH,wBAJW,KAAK,CAAC,OAAO,CAAC,aACd,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAClC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAMnC;IAED;;;;;;;OAOG;IACH,kBALW,MAAM,OACN,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,oBALW,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,4BAbW,OAAO,GACL,OAAO,CA+BnB;IAED;;;;;;;;;;;;;;;OAeG;IACH,uBAXW,OAAO,GACL,OAAO,CAgBnB;CACF;qBAhgBoB,eAAe"}
+{"version":3,"file":"Data.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/Data.js"],"names":[],"mappings":"AAUA;IACA;;;;;OAKG;IACD,mBAFQ,KAAK,CAAC,MAAM,CAAC,CAgBnB;IAEF;;;;;OAKG;IACH,qBAFU,KAAK,CAAC,MAAM,CAAC,CAmBrB;IAEF;;;;;;;OAOG;IACH,kBAFU,KAAK,CAAC,MAAM,CAAC,CAKrB;IAEF;;;;;OAKG;IACH,uBAFU,KAAK,CAAC,MAAM,CAAC,CAE2D;IAElF;;;;;;OAMG;IACH,sBAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAMlB;IAED;;;;;;OAMG;IACH,uBAJW,MAAM,WACN,MAAM,GACJ,MAAM,CAMlB;IAED;;;;;;;;;;;OAWG;IACH,yBATW,MAAM,UACN,MAAM,oBACN,OAAO,GACL,MAAM,CAWlB;IAED;;;;;;;;;;;OAWG;IACH,wBATW,MAAM,UACN,MAAM,oBACN,OAAO,GACL,MAAM,CAWlB;IAED;;;;;;;OAOG;IACH,yBALW,MAAM,UACN,MAAM,oBACN,OAAO,GACL,MAAM,CAWlB;IAED;;;;;;;OAOG;IACH,0BALW,MAAM,UACN,MAAM,oBACN,OAAO,GACL,MAAM,CAYlB;IAED;;;;;OAKG;IAEH;;;;;OAKG;IAEH;;;;;;;OAOG;IACH,2BAJW,MAAM;;;;oBAdH,MAAM;QAgBP,KAAK,CAAC,MAAM,CAAC,CAIzB;IAED;;;;;;;OAOG;IACH,qBALW,OAAO,QACP,MAAM,GAAC,QAAQ;;;;qBAnBZ,OAAO;QAqBR,OAAO,CAQnB;IAED;;;;;OAKG;IACH,yBAHW,MAAM,GACJ,OAAO,CASnB;IAED;;;;;;;;OAQG;IACH,yBAJW,OAAO,QACP,MAAM,GACJ,OAAO,CAwBnB;IAED;;;;;OAKG;IACH,qBAHW,OAAO,GACL,MAAM,CAclB;IAED;;;;;OAKG;IACH,wBAHW,OAAO,GACL,OAAO,CAInB;IAED;;;;;;;;OAQG;IACH,sBALW,OAAO,oBACP,OAAO,GAEL,OAAO,CA8BnB;IAED;;;;;OAKG;IACH,6BAHW,MAAM,GACJ,MAAM,CAmBlB;IAED;;;;;;;OAOG;IACH,6BAJW,MAAM,QACN,KAAK,CAAC,MAAM,CAAC,GACX,MAAM,CAiBlB;IAED;;;;;;;OAOG;IACH,2BAJW,MAAM,QACN,KAAK,CAAC,MAAM,CAAC,SACb,OAAO,QAMjB;IAED;;;;;OAKG;IACH,+BAHc,MAAM,EAAA,GACP,MAAM,CAqBlB;IAED;;;;;;;OAOG;IACH,wBAJW,KAAK,CAAC,OAAO,CAAC,aACd,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAClC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAMnC;IAED;;;;;;;OAOG;IACH,kBALW,MAAM,OACN,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,oBALW,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,4BAbW,OAAO,GACL,OAAO,CA+BnB;IAED;;;;;;;;;;;;;;;OAeG;IACH,uBAXW,OAAO,GACL,OAAO,CAgBnB;CACF;qBA9gBoB,eAAe"}

package/types/browser/lib/OObject.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @typedef {object} OObjectArrayInfo
+ * @property {Array<string>} path - The path array to the array element
+ * @property {string} flatPath - The dot-separated path to the array element
+ * @property {number} index - The index of the element in the array
+ */
+/**
+ * @typedef {object} OObjectEntry
+ * @property {string} key - The property key
+ * @property {any} value - The property value
+ * @property {string} valueString - String representation of the value
+ * @property {Array<string>} path - The path array to this property
+ * @property {string} flatPath - The dot-separated path to this property
+ * @property {OObjectArrayInfo} [array] - Array information if this entry is from an array
+ */
+/**
+ * @typedef {Record<string, any> | Array<any>} OObjectSource
+ */
+export default class OObject {
+    /**
+     * Creates an OObject from a source object or array
+     *
+     * @param {OObjectSource} source - The source object or array to decompose
+     * @returns {OObject} A new OObject instance
+     */
+    static from(source: OObjectSource): OObject;
+    /**
+     * Decomposes a nested object into flat entries with path information.
+     * Recursively processes objects and arrays to create a flat structure for
+     * evaluation.
+     *
+     * @param {Record<string, any>} work - The object to decompose
+     * @param {Array<string>} objectPath - Current path array for nested properties
+     * @returns {Array<OObjectEntry>} Array of decomposed object entries with path information
+     */
+    static "__#private@#decomposeObject"(work: Record<string, any>, objectPath?: Array<string>): Array<OObjectEntry>;
+    /**
+     * Constructs an OObject with optional initial data.
+     *
+     * @param {Array<OObjectEntry>} oobject
+     */
+    constructor(oobject?: Array<OObjectEntry>);
+    /**
+     * Gets the internal data array
+     *
+     * @returns {Array<object>} The decomposed object entries
+     */
+    get data(): Array<object>;
+    /**
+     * Finds the first entry matching a flat path or predicate
+     *
+     * @param {string|((entry: OObjectEntry, index: number, array: Array<OObjectEntry>) => boolean)} pathOrPredicate - Flat path string or predicate function
+     * @returns {OObjectEntry|undefined} The matching entry or undefined
+     */
+    find(pathOrPredicate: string | ((entry: OObjectEntry, index: number, array: Array<OObjectEntry>) => boolean)): OObjectEntry | undefined;
+    /**
+     * Finds all entries matching a flat path or predicate
+     *
+     * @param {string|((entry: OObjectEntry, index: number, array: Array<OObjectEntry>) => boolean)} pathOrPredicate - Flat path string or predicate function
+     * @returns {Array<object>} Array of matching entries
+     */
+    findAll(pathOrPredicate: string | ((entry: OObjectEntry, index: number, array: Array<OObjectEntry>) => boolean)): Array<object>;
+    /**
+     * Returns an iterator over all entries in order
+     *
+     * @returns {Iterator<object>} Iterator of decomposed entries
+     */
+    entries(): Iterator<object>;
+    /**
+     * Executes a callback for each entry in order
+     *
+     * @param {(entry: OObjectEntry, index: number, array: Array<OObjectEntry>) => void} callback - Function to call for each entry
+     * @returns {void}
+     */
+    forEach(callback: (entry: OObjectEntry, index: number, array: Array<OObjectEntry>) => void): void;
+    /**
+     * Ensures a path exists in the data, optionally setting a value
+     *
+     * @param {string} flatPath - The dot-separated path to ensure
+     * @param {*} value - Optional value to set (defaults to undefined)
+     * @returns {object} The entry at the path
+     */
+    assurePath(flatPath: string, value?: any): object;
+    #private;
+}
+export type OObjectArrayInfo = {
+    /**
+     * - The path array to the array element
+     */
+    path: Array<string>;
+    /**
+     * - The dot-separated path to the array element
+     */
+    flatPath: string;
+    /**
+     * - The index of the element in the array
+     */
+    index: number;
+};
+export type OObjectEntry = {
+    /**
+     * - The property key
+     */
+    key: string;
+    /**
+     * - The property value
+     */
+    value: any;
+    /**
+     * - String representation of the value
+     */
+    valueString: string;
+    /**
+     * - The path array to this property
+     */
+    path: Array<string>;
+    /**
+     * - The dot-separated path to this property
+     */
+    flatPath: string;
+    /**
+     * - Array information if this entry is from an array
+     */
+    array?: OObjectArrayInfo;
+};
+export type OObjectSource = Record<string, any> | Array<any>;
+//# sourceMappingURL=OObject.d.ts.map

package/types/browser/lib/OObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OObject.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/OObject.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH;;;;;;;;GAQG;AAEH;;GAEG;AAEH;IAaE;;;;;OAKG;IACH,oBAHW,aAAa,GACX,OAAO,CAMnB;IAED;;;;;;;;OAQG;IACH,2CAJW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,eACnB,KAAK,CAAC,MAAM,CAAC,GACX,KAAK,CAAC,YAAY,CAAC,CAyC/B;IArED;;;;OAIG;IACH,sBAFW,KAAK,CAAC,YAAY,CAAC,EAI7B;IAgED;;;;OAIG;IACH,YAFa,KAAK,CAAC,MAAM,CAAC,CAIzB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GAAC,CAAC,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,KAAK,OAAO,CAAC,GAClF,YAAY,GAAC,SAAS,CAUlC;IAED;;;;;OAKG;IACH,yBAHW,MAAM,GAAC,CAAC,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,KAAK,OAAO,CAAC,GAClF,KAAK,CAAC,MAAM,CAAC,CAUzB;IAED;;;;OAIG;IACH,WAFa,QAAQ,CAAC,MAAM,CAAC,CAI5B;IAED;;;;;OAKG;IACH,kBAHW,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,KAAK,IAAI,GACtE,IAAI,CAMhB;IAED;;;;;;OAMG;IACH,qBAJW,MAAM,UACN,GAAC,GACC,MAAM,CA4BlB;;CACF;;;;;UA9La,KAAK,CAAC,MAAM,CAAC;;;;cACb,MAAM;;;;WACN,MAAM;;;;;;SAKN,MAAM;;;;WACN,GAAG;;;;iBACH,MAAM;;;;UACN,KAAK,CAAC,MAAM,CAAC;;;;cACb,MAAM;;;;YACN,gBAAgB;;4BAIjB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC"}

package/types/browser/lib/Promised.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Promised.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/Promised.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH;IACE;;;;;;OAMG;IACH,uBAHW,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GACrB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAMnC;IAED;;;;;;OAMG;IACH,sBAHW,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GACrB,OAAO,CAAC,OAAO,CAAC,CAM5B;IAED;;;;;;OAMG;IACH,wBAHW,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GACrB,OAAO,CAAC,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,CAAC,CAM/F;IAED;;;;;OAKG;IACH,4BAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,OAAO,CAInB;IAED;;;;;OAKG;IACH,6BAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,OAAO,CAInB;IAED;;;;;OAKG;IACH,yBAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,KAAK,CAAC;QAAC,MAAM,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAC,CAAC,CAIxD;IAED;;;;;OAKG;IACH,yBAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAC,CAAC,CAIxD;IAED;;;;;OAKG;IACH,wBAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,KAAK,CAAC,OAAO,CAAC,CAO1B;IAED;;;;;OAKG;IACH,uBAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,KAAK,CAAC,OAAO,CAAC,CAO1B;IAED;;;;;;OAMG;IACH,sBAJW,MAAM,WACN,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,QAWpF;CACF"}
+{"version":3,"file":"Promised.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/Promised.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH;IACE;;;;;;OAMG;IACH,uBAHW,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GACrB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAMnC;IAED;;;;;;OAMG;IACH,sBAHW,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GACrB,OAAO,CAAC,OAAO,CAAC,CAM5B;IAED;;;;;;OAMG;IACH,wBAHW,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GACrB,OAAO,CAAC,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,CAAC,CAM/F;IAED;;;;;OAKG;IACH,4BAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,OAAO,CAInB;IAED;;;;;OAKG;IACH,6BAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,OAAO,CAInB;IAED;;;;;OAKG;IACH,yBAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,KAAK,CAAC;QAAC,MAAM,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAC,CAAC,CAIxD;IAED;;;;;OAKG;IACH,yBAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAC,CAAC,CAIxD;IAED;;;;;OAKG;IACH,wBAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,KAAK,CAAC,OAAO,CAAC,CAO1B;IAED;;;;;OAKG;IACH,uBAHW,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,GACxE,KAAK,CAAC,OAAO,CAAC,CAO1B;IAED;;;;;;OAMG;IACH,sBAJW,MAAM,WACN,KAAK,CAAC;QAAC,MAAM,EAAE,WAAW,GAAC,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC,QAapF;CACF"}

package/types/browser/lib/Time.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/Time.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH;IACE;;;;;;;;;;;;;;;;;;OAkBG;IACH,oBAfW,MAAM,UACN,OAAO,GACL,OAAO,CAAC,OAAO,CAAC,GAAG;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAwBhD;IAED;;;;;;;;;OASG;IACH,uBANW,OAAO,CAAC,OAAO,CAAC,GAAG;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC,GACnC,IAAI,CAQhB;CACF"}
+{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/Time.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH;IACE;;;;;;;;;;;;;;;;;;OAkBG;IACH,oBAfW,MAAM,UACN,OAAO,GACL,OAAO,CAAC,OAAO,CAAC,GAAG;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CA0BhD;IAED;;;;;;;;;OASG;IACH,uBANW,OAAO,CAAC,OAAO,CAAC,GAAG;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC,GACnC,IAAI,CAQhB;CACF"}

package/types/browser/lib/TypeSpec.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Options for creating a new TypeSpec.
+ *
+ * @typedef {object} TypeSpecOptions
+ * @property {string} [delimiter="|"] - The delimiter for union types
+ */
+/**
+ * Options for type validation methods.
+ *
+ * @typedef {object} TypeValidationOptions
+ * @property {boolean} [allowEmpty=true] - Whether empty values are allowed
+ */
 /**
  * Type specification class for parsing and validating complex type definitions.
  * Supports union types, array types, and validation options.
@@ -7,9 +19,9 @@ export default class TypeSpec {
      * Creates a new TypeSpec instance.
      *
      * @param {string} string - The type specification string (e.g., "string|number", "object[]")
-     * @param {unknown} options - Additional parsing options
+     * @param {TypeSpecOptions} [options] - Additional parsing options
      */
-    constructor(string: string, options: unknown);
+    constructor(string: string, options?: TypeSpecOptions);
     specs: any[];
     length: number;
     stringRepresentation: string;
@@ -79,12 +91,36 @@ export default class TypeSpec {
      * Handles array types, union types, and empty value validation.
      *
      * @param {unknown} value - The value to test against the type specifications
-     * @param {unknown} options - Validation options
-     * @param {boolean} options.allowEmpty - Whether empty values are allowed
+     * @param {TypeValidationOptions} [options] - Validation options
      * @returns {boolean} True if the value matches any type specification
      */
-    matches(value: unknown, options: unknown): boolean;
-    match(value: any, options: any): unknown[];
+    matches(value: unknown, options?: TypeValidationOptions): boolean;
+    /**
+     * Returns matching type specifications for a value.
+     *
+     * @param {unknown} value - The value to test against the type specifications
+     * @param {TypeValidationOptions} [options] - Validation options
+     * @returns {Array<object>} Array of matching type specifications
+     */
+    match(value: unknown, options?: TypeValidationOptions): Array<object>;
     #private;
 }
+/**
+ * Options for creating a new TypeSpec.
+ */
+export type TypeSpecOptions = {
+    /**
+     * - The delimiter for union types
+     */
+    delimiter?: string;
+};
+/**
+ * Options for type validation methods.
+ */
+export type TypeValidationOptions = {
+    /**
+     * - Whether empty values are allowed
+     */
+    allowEmpty?: boolean;
+};
 //# sourceMappingURL=TypeSpec.d.ts.map

package/types/browser/lib/TypeSpec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TypeSpec.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/TypeSpec.js"],"names":[],"mappings":"AAWA;;;GAGG;AACH;IAGE;;;;;OAKG;IACH,oBAHW,MAAM,WACN,OAAO,EAUjB;IAJC,aAAwB;IACxB,eAAgC;IAChC,6BAA2C;IAI7C;;;;OAIG;IACH,YAFa,MAAM,CAQlB;IAED;;;;OAIG;IACH,UAFa,OAAO,CASnB;IAED;;;;OAIG;IACH,kBAFW,CAAS,IAAO,EAAP,OAAO,KAAG,IAAI,QAIjC;IAED;;;;;OAKG;IACH,gBAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,OAAO,CAInB;IAED;;;;;OAKG;IACH,eAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,OAAO,CAInB;IAED;;;;;OAKG;IACH,iBAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,KAAK,CAAC,OAAO,CAAC,CAI1B;IAED;;;;;OAKG;IACH,cAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,KAAK,CAAC,OAAO,CAAC,CAI1B;IAED;;;;;;OAMG;IACH,iBAJW,CAAS,IAAO,EAAP,OAAO,EAAE,IAAO,EAAP,OAAO,KAAG,OAAO,gBACnC,OAAO,GACL,OAAO,CAInB;IAED;;;;;OAKG;IACH,eAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,MAAM,GAAC,SAAS,CAI5B;IAED;;;;;;;;OAQG;IACH,eALW,OAAO,WACP,OAAO,GAEL,OAAO,CAInB;IAED,2CA6DC;;CAmDF"}
+{"version":3,"file":"TypeSpec.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/TypeSpec.js"],"names":[],"mappings":"AAWA;;;;;GAKG;AAEH;;;;;GAKG;AAEH;;;GAGG;AACH;IAGE;;;;;OAKG;IACH,oBAHW,MAAM,YACN,eAAe,EAUzB;IAJC,aAAwB;IACxB,eAAgC;IAChC,6BAA2C;IAI7C;;;;OAIG;IACH,YAFa,MAAM,CAQlB;IAED;;;;OAIG;IACH,UAFa,OAAO,CASnB;IAED;;;;OAIG;IACH,kBAFW,CAAS,IAAO,EAAP,OAAO,KAAG,IAAI,QAIjC;IAED;;;;;OAKG;IACH,gBAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,OAAO,CAInB;IAED;;;;;OAKG;IACH,eAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,OAAO,CAInB;IAED;;;;;OAKG;IACH,iBAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,KAAK,CAAC,OAAO,CAAC,CAI1B;IAED;;;;;OAKG;IACH,cAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,KAAK,CAAC,OAAO,CAAC,CAI1B;IAED;;;;;;OAMG;IACH,iBAJW,CAAS,IAAO,EAAP,OAAO,EAAE,IAAO,EAAP,OAAO,KAAG,OAAO,gBACnC,OAAO,GACL,OAAO,CAInB;IAED;;;;;OAKG;IACH,eAHW,CAAS,IAAO,EAAP,OAAO,KAAG,OAAO,GACxB,MAAM,GAAC,SAAS,CAI5B;IAED;;;;;;;OAOG;IACH,eAJW,OAAO,YACP,qBAAqB,GACnB,OAAO,CAInB;IAED;;;;;;OAMG;IACH,aAJW,OAAO,YACP,qBAAqB,GACnB,KAAK,CAAC,MAAM,CAAC,CA+DzB;;CAkDF;;;;;;;;gBApQa,MAAM;;;;;;;;;iBAON,OAAO"}