@gesslar/toolkit 3.6.3 → 3.8.0

package/README.md

@@ -2,14 +2,16 @@
 
 [![CodeQL, Linting, Testing](https://github.com/gesslar/toolkit/actions/workflows/Quality.yaml/badge.svg)](https://github.com/gesslar/toolkit/actions/workflows/Quality.yaml)
 
-A collection of utilities for Node.js and browser environments, including file and directory abstractions, terminal utilities, validation helpers, and data manipulation functions.
+A collection of utilities for Node.js and browser environments, including file
+and directory abstractions, terminal utilities, validation helpers, and data
+manipulation functions.
 
 ## Included Classes
 
 ### Browser
 
-These classes exist and function within the browser, or browser-like environment, such as
-a Tauri app.
+These classes exist and function within the browser, or browser-like
+environment, such as a Tauri app.
 
 | Name | Description |
 | ---- | ----------- |
@@ -34,18 +36,15 @@ Includes all browser functionality plus Node.js-specific modules for file I/O, l
 | ---- | ----------- |
 | Cache | Cache management for file I/O operations |
 | CappedDirectoryObject | Directory operations constrained to a specific tree |
-| Contract | Contract management and validation |
 | DirectoryObject | Directory metadata and operations including path resolution, existence checks, and traversal |
 | FileObject | File system wrapper for file operations |
 | FS | Base class for file system operations with static utilities |
 | Glog | Logging framework |
 | Notify | Event system wrapper for Node.js events |
 | Sass | Custom Error class with enhanced features |
-| Schemer | JSON schema validation and management |
 | Tantrum | AggregateError implementation |
 | TempDirectoryObject | Temporary directory management with automatic cleanup |
 | Term | Terminal formatting and output utilities |
-| Terms | Terms for use with Contract |
 | Util | General utility functions (Node-enhanced version) |
 | Valid | Validation and assertion methods |
 
@@ -57,13 +56,15 @@ npm i @gesslar/toolkit
 
 ## Usage
 
-Toolkit is environment aware and automatically detects whether it is being used in a web browser or in Node.js. You can optionally specify the `node` or `browser` variant explicitly.
+Toolkit is environment aware and automatically detects whether it is being used
+in a web browser or in Node.js. You can optionally specify the `node` or
+`browser` variant explicitly.
 
 ### Browser-like
 
-TypeScript editors do not pick up types from jsDelivr. If you want inline types without
-installing from npm, use the esm.sh `?dts` URL or install the package locally for
-development and use the CDN at runtime.
+TypeScript editors do not pick up types from jsDelivr. If you want inline types
+without installing from npm, use the esm.sh `?dts` URL or install the package
+locally for development and use the CDN at runtime.
 
 #### jsDelivr (runtime only)
 
@@ -96,12 +97,24 @@ import {Data, FileObject} from "@gesslar/toolkit/node"
 import { Data, Collection, Util } from '@gesslar/toolkit/browser'
 ```
 
-The browser version includes: Collection, Data, Disposer, HTML, Notify, Sass, Tantrum, Type (TypeSpec), Util, and Valid. Node-only modules (Cache, CappedDirectoryObject, Contract, DirectoryObject, FileObject, FS, Glog, Schemer, TempDirectoryObject, Term, Terms) are not available in the browser version.
+The browser version includes: Collection, Data, Disposer, HTML, Notify, Sass,
+Tantrum, Type (TypeSpec), Util, and Valid. Node-only modules (Cache,
+CappedDirectoryObject, DirectoryObject, FileObject, FS, Glog,
+TempDirectoryObject, Term) are not available in the browser version.
 
 ## Post Partum
 
-If you made it this far, please understand that I have absolutely zero scruples when it comes to breaking changes. Primarily, the audience for this library is myself. Consequently, anything that relies on the contents of this library will dutifully crash and I'll have to refactor those things then. It's like playing nicky nicky nine doors. But with myself. And there's a lazy bomb waiting for me. That I planted. For me. And the bomb just explodes poop.
-
-You're of course welcome to use my library! It's pretty robust. Uhhh, but maybe lock in the version until you see if something is gonna poop all over you. I make robots make my PR notifications and generally they're very good at firing off klaxons about my fetish for breaking changes, so you should be all right if you're paying attention. 🤷🏻
+If you made it this far, please understand that I have absolutely zero scruples
+when it comes to breaking changes. Primarily, the audience for this library is
+myself. Consequently, anything that relies on the contents of this library will
+dutifully crash and I'll have to refactor those things then. It's like playing
+nicky nicky nine doors. But with myself. And there's a lazy bomb waiting for
+me. That I planted. For me. And the bomb just explodes poop.
+
+You're of course welcome to use my library! It's pretty robust. Uhhh, but maybe
+lock in the version until you see if something is gonna poop all over you. I
+make robots make my PR notifications and generally they're very good at firing
+off klaxons about my fetish for breaking changes, so you should be all right
+if you're paying attention. 🤷🏻
 
 Sincerely, Senator Yabba of the Dabba (Doo)

package/package.json

@@ -3,10 +3,9 @@
   "description": "A collection of utilities for Node.js and browser environments.",
   "author": {
     "name": "gesslar",
-    "email": "bmw@gesslar.dev",
     "url": "https://gesslar.dev"
   },
-  "version": "3.6.3",
+  "version": "3.8.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -48,20 +47,20 @@
     "src/",
     "UNLICENSE.txt"
   ],
-  "sideEffects": false,
   "engines": {
     "node": ">=22"
   },
   "dependencies": {
-    "@gesslar/colours": "^0.5.0",
+    "@gesslar/colours": "^0.7.1",
     "ajv": "^8.17.1",
     "globby": "^16.1.0",
     "json5": "^2.2.3",
     "yaml": "^2.8.2"
   },
   "devDependencies": {
-    "@gesslar/uglier": "^0.4.0",
+    "@gesslar/uglier": "^0.5.1",
     "eslint": "^9.39.2",
+    "happy-dom": "^20.0.11",
     "typescript": "^5.9.3"
   },
   "scripts": {
@@ -71,6 +70,8 @@
     "submit": "pnpm publish --access public --//registry.npmjs.org/:_authToken=\"${NPM_ACCESS_TOKEN}\"",
     "update": "pnpm up --latest --recursive",
     "test": "node --test tests/**/*.test.js",
+    "test:node": "node --test tests/node/*.test.js",
+    "test:browser": "node --test tests/browser/*.test.js",
     "pr": "gt submit -p --ai",
     "patch": "pnpm version patch",
     "minor": "pnpm version minor",

package/src/index.js

@@ -16,13 +16,10 @@ export {default as Util} from "./lib/Util.js"
 // Node-specific exports
 export {default as Cache} from "./lib/Cache.js"
 export {default as CappedDirectoryObject} from "./lib/CappedDirectoryObject.js"
-export {default as Contract} from "./lib/Contract.js"
 export {default as DirectoryObject} from "./lib/DirectoryObject.js"
 export {default as TempDirectoryObject} from "./lib/TempDirectoryObject.js"
 export {default as FileObject} from "./lib/FileObject.js"
 export {default as FS} from "./lib/FS.js"
 export {default as Glog} from "./lib/Glog.js"
 export {default as Notify} from "./lib/Notify.js"
-export {default as Schemer} from "./lib/Schemer.js"
 export {default as Term} from "./lib/Term.js"
-export {default as Terms} from "./lib/Terms.js"

package/src/lib/CappedDirectoryObject.js

@@ -132,6 +132,16 @@ export default class CappedDirectoryObject extends DirectoryObject {
     }
   }
 
+  /**
+   * Re-caps this directory to itself, making it the new root of the capped tree.
+   * This is a protected method intended for use by subclasses like TempDirectoryObject.
+   *
+   * @protected
+   */
+  _recapToSelf() {
+    this.#cap = this.#realPath
+  }
+
   /**
    * Returns the cap path for this directory.
    *
@@ -221,14 +231,14 @@ export default class CappedDirectoryObject extends DirectoryObject {
    * Returns the parent directory of this capped directory.
    * Returns null only if this directory is at the cap (the "root" of the capped tree).
    *
-   * Note: The returned parent is a plain DirectoryObject (not capped).
-   * Use getDirectory() for creating capped subdirectories.
+   * Note: The returned parent is a CappedDirectoryObject with the same cap.
+   * This maintains the capping behavior throughout the directory hierarchy.
    *
-   * @returns {DirectoryObject|null} Parent directory or null if at cap root
+   * @returns {CappedDirectoryObject|null} Parent directory or null if at cap root
    * @example
    * const capped = new TempDirectoryObject("myapp")
    * const subdir = capped.getDirectory("data")
-   * console.log(subdir.parent.path) // Returns parent DirectoryObject
+   * console.log(subdir.parent.path) // Returns parent CappedDirectoryObject
    * console.log(capped.parent) // null (at cap root)
    */
   get parent() {
@@ -239,13 +249,17 @@ export default class CappedDirectoryObject extends DirectoryObject {
       return null
     }
 
-    // Otherwise return the parent using real path (plain DirectoryObject, not capped)
+    // Compute parent's real path
     const parentPath = path.dirname(this.#realPath)
     const isRoot = parentPath === this.#realPath
 
-    return isRoot
-      ? null
-      : new DirectoryObject(parentPath, this.temporary)
+    if(isRoot) {
+      return null
+    }
+
+    // Compute relative path from current to parent (just "..")
+    // Then use getDirectory to create the parent, which preserves the class type
+    return this.getDirectory("..")
   }
 
   /**
@@ -264,9 +278,24 @@ export default class CappedDirectoryObject extends DirectoryObject {
    */
   toJSON() {
     const capResolved = path.resolve(this.#cap)
-    const parentPath = this.#realPath === capResolved
-      ? null
-      : "/"
+    let parentPath
+
+    if(this.#realPath === capResolved) {
+      // At cap root, no parent
+      parentPath = null
+    } else {
+      // Compute parent's virtual path
+      const parentReal = path.dirname(this.#realPath)
+      const relative = path.relative(capResolved, parentReal)
+
+      // If parent is cap root or empty, return "/"
+      if(!relative || relative === ".") {
+        parentPath = "/"
+      } else {
+        // Return parent's virtual path with leading slash
+        parentPath = "/" + relative.split(path.sep).join("/")
+      }
+    }
 
     return {
       supplied: this.supplied,
@@ -278,6 +307,7 @@ export default class CappedDirectoryObject extends DirectoryObject {
       isFile: this.isFile,
       isDirectory: this.isDirectory,
       parent: parentPath,
+      root: this.root.path,
       real: this.real.toJSON()
     }
   }
@@ -436,10 +466,11 @@ export default class CappedDirectoryObject extends DirectoryObject {
     // Start at cap root
     let current = this.#createCappedAtRoot()
 
-    // Traverse each segment, creating CappedDirectoryObject instances
-    // (not subclass instances, to avoid constructor signature issues)
+    // Traverse each segment, using constructor to preserve class type
     for(const segment of segments) {
-      current = new CappedDirectoryObject(segment, current, this.temporary)
+      // Use simple name constructor to preserve subclass type
+      // Works for both CappedDirectoryObject and TempDirectoryObject
+      current = new this.constructor(segment, current, this.temporary)
     }
 
     return current

package/src/lib/DirectoryObject.js

@@ -157,7 +157,8 @@ export default class DirectoryObject extends FS {
       extension: this.extension,
       isFile: this.isFile,
       isDirectory: this.isDirectory,
-      parent: this.parent ? this.parent.path : null
+      parent: this.parent ? this.parent.path : null,
+      root: this.root.path
     }
   }
 
@@ -294,6 +295,34 @@ export default class DirectoryObject extends FS {
     return this.#parent
   }
 
+  /**
+   * Returns the root directory of the filesystem.
+   *
+   * For DirectoryObject, this walks up to the filesystem root.
+   * For CappedDirectoryObject, this returns the cap root.
+   *
+   * @returns {DirectoryObject} The root directory
+   * @example
+   * const dir = new DirectoryObject("/usr/local/bin")
+   * console.log(dir.root.path)  // "/"
+   *
+   * @example
+   * const capped = new CappedDirectoryObject("/projects/myapp")
+   * const sub = capped.getDirectory("src/lib")
+   * console.log(sub.root.path)  // "/" (virtual, cap root)
+   * console.log(sub.root.real.path)  // "/projects/myapp"
+   */
+  get root() {
+    // Walk up until we find a directory with no parent
+    let current = this
+
+    while(current.parent !== null) {
+      current = current.parent
+    }
+
+    return current
+  }
+
   /**
    * Recursively removes a temporary directory and all its contents.
    *

package/src/lib/TempDirectoryObject.js

@@ -99,11 +99,13 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
         )
       }
 
-      // SECURITY: Ensure parent's cap is tmpdir (prevent escape to other caps)
-      const tmpdir = os.tmpdir()
-      if(parent.cap !== tmpdir) {
+      // SECURITY: Ensure parent's cap is within tmpdir (prevent escape to other caps)
+      const tmpdir = path.resolve(os.tmpdir())
+      const parentCap = path.resolve(parent.cap)
+
+      if(!parentCap.startsWith(tmpdir)) {
         throw Sass.new(
-          `Parent must be capped to OS temp directory (${tmpdir}), ` +
+          `Parent must be capped to OS temp directory (${tmpdir}) or a subdirectory thereof, ` +
           `got cap: ${parent.cap}`
         )
       }
@@ -119,6 +121,13 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
 
     // Temp-specific behavior: create directory immediately
     this.#createDirectory()
+
+    // Re-cap to the temp directory itself for consistent behavior with CappedDirectoryObject
+    // This makes temp.cap === temp.real.path and temp.parent === null
+    if(!parent) {
+      // Only re-cap if this is a root temp directory (no TempDirectoryObject parent)
+      this._recapToSelf()
+    }
   }
 
   /**

package/src/types/index.d.ts

@@ -9,15 +9,12 @@ export { default as Tantrum } from "./lib/Tantrum.js";
 export { default as Util } from "./lib/Util.js";
 export { default as Cache } from "./lib/Cache.js";
 export { default as CappedDirectoryObject } from "./lib/CappedDirectoryObject.js";
-export { default as Contract } from "./lib/Contract.js";
 export { default as DirectoryObject } from "./lib/DirectoryObject.js";
 export { default as TempDirectoryObject } from "./lib/TempDirectoryObject.js";
 export { default as FileObject } from "./lib/FileObject.js";
 export { default as FS } from "./lib/FS.js";
 export { default as Glog } from "./lib/Glog.js";
 export { default as Notify } from "./lib/Notify.js";
-export { default as Schemer } from "./lib/Schemer.js";
 export { default as Term } from "./lib/Term.js";
-export { default as Terms } from "./lib/Terms.js";
 export { default as Disposer, Disposer as DisposerClass } from "./browser/lib/Disposer.js";
 //# sourceMappingURL=index.d.ts.map

package/src/types/lib/CappedDirectoryObject.d.ts

@@ -37,6 +37,13 @@ export default class CappedDirectoryObject extends DirectoryObject {
      * // path: /home/user/.cache/etc/config, cap: /home/user/.cache
      */
     constructor(dirPath: string, parent?: CappedDirectoryObject | null, temporary?: boolean);
+    /**
+     * Re-caps this directory to itself, making it the new root of the capped tree.
+     * This is a protected method intended for use by subclasses like TempDirectoryObject.
+     *
+     * @protected
+     */
+    protected _recapToSelf(): void;
     /**
      * Returns the cap path for this directory.
      *
@@ -75,6 +82,21 @@ export default class CappedDirectoryObject extends DirectoryObject {
      * subdir.real.parent              // Can traverse outside the cap
      */
     get real(): DirectoryObject;
+    /**
+     * Returns the parent directory of this capped directory.
+     * Returns null only if this directory is at the cap (the "root" of the capped tree).
+     *
+     * Note: The returned parent is a CappedDirectoryObject with the same cap.
+     * This maintains the capping behavior throughout the directory hierarchy.
+     *
+     * @returns {CappedDirectoryObject|null} Parent directory or null if at cap root
+     * @example
+     * const capped = new TempDirectoryObject("myapp")
+     * const subdir = capped.getDirectory("data")
+     * console.log(subdir.parent.path) // Returns parent CappedDirectoryObject
+     * console.log(capped.parent) // null (at cap root)
+     */
+    get parent(): CappedDirectoryObject | null;
     /**
      * Returns the URL with virtual path (cap-relative).
      *

package/src/types/lib/CappedDirectoryObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CappedDirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/CappedDirectoryObject.js"],"names":[],"mappings":"AAkBA;;;;;;;;GAQG;AACH;IAGE;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,qBArBW,MAAM,WACN,qBAAqB,OAAC,cACtB,OAAO,EA0EjB;IAqBD;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,0BAFa,MAAM,CAIlB;IAqCD;;;;;;;;;;;;;;;;;OAiBG;IACH,YAba,eAAe,CAe3B;IAiCD;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAqED;;;;OAIG;IACH,cAFa,SAAS,CAAC,eAAe,CAAC,CAItC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,sBAjBW,MAAM,GACJ,qBAAqB,CAiEjC;IAqID;;;;;OAKG;IACH,WAHW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,QAAO;KAAC,CAAC,CAgBnE;;CA8DF;4BAnmB2B,sBAAsB;uBAC3B,iBAAiB"}
+{"version":3,"file":"CappedDirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/CappedDirectoryObject.js"],"names":[],"mappings":"AAkBA;;;;;;;;GAQG;AACH;IAGE;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,qBArBW,MAAM,WACN,qBAAqB,OAAC,cACtB,OAAO,EA0EjB;IAqBD;;;;;OAKG;IACH,+BAEC;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,0BAFa,MAAM,CAIlB;IAqCD;;;;;;;;;;;;;;;;;OAiBG;IACH,YAba,eAAe,CAe3B;IAED;;;;;;;;;;;;;OAaG;IACH,cAPa,qBAAqB,GAAC,IAAI,CA0BtC;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAqFD;;;;OAIG;IACH,cAFa,SAAS,CAAC,eAAe,CAAC,CAItC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,sBAjBW,MAAM,GACJ,qBAAqB,CAiEjC;IAsID;;;;;OAKG;IACH,WAHW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,QAAO;KAAC,CAAC,CAgBnE;;CA8DF;4BAloB2B,sBAAsB;uBAC3B,iBAAiB"}

package/src/types/lib/DirectoryObject.d.ts

@@ -139,6 +139,24 @@ export default class DirectoryObject extends FS {
      * console.log(root.parent) // null
      */
     get parent(): DirectoryObject | null;
+    /**
+     * Returns the root directory of the filesystem.
+     *
+     * For DirectoryObject, this walks up to the filesystem root.
+     * For CappedDirectoryObject, this returns the cap root.
+     *
+     * @returns {DirectoryObject} The root directory
+     * @example
+     * const dir = new DirectoryObject("/usr/local/bin")
+     * console.log(dir.root.path)  // "/"
+     *
+     * @example
+     * const capped = new CappedDirectoryObject("/projects/myapp")
+     * const sub = capped.getDirectory("src/lib")
+     * console.log(sub.root.path)  // "/" (virtual, cap root)
+     * console.log(sub.root.real.path)  // "/projects/myapp"
+     */
+    get root(): DirectoryObject;
     /**
      * Recursively removes a temporary directory and all its contents.
      *

package/src/types/lib/DirectoryObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/DirectoryObject.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;uBAqGe,MAAM;IAlEnB;;;;;OAKG;IACH,yCAFW,OAAO,EA6BjB;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAclB;IAWD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,aALa,KAAK,CAAC,MAAM,CAAC,CAOzB;IAED;;;;OAIG;IACH,iBAFa,OAAO,CAInB;IAED;;;;;;;;;;;;OAYG;IACH,cARa,eAAe,GAAC,IAAI,CAwBhC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,UATa,OAAO,CAAC,IAAI,CAAC,CA0BzB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAiBD;;;;;;;;;;;;;;;OAeG;IACH,WAZW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAoCpF;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAqBzB;IA8BD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,MAAM,CAclB;IAED;;;;;;;;;;;;;;OAcG;IACH,UARa,OAAO,CAAC,IAAI,CAAC,CAkBzB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAM5B;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAO5B;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,sBAdW,MAAM,GACJ,eAAe,CAoB3B;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,kBAbW,MAAM,GACJ,UAAU,CAkBtB;;CACF;eAtkBc,SAAS;uBACD,iBAAiB"}
+{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/DirectoryObject.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;uBAsGe,MAAM;IAnEnB;;;;;OAKG;IACH,yCAFW,OAAO,EA6BjB;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAelB;IAWD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,aALa,KAAK,CAAC,MAAM,CAAC,CAOzB;IAED;;;;OAIG;IACH,iBAFa,OAAO,CAInB;IAED;;;;;;;;;;;;OAYG;IACH,cARa,eAAe,GAAC,IAAI,CAwBhC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,YAXa,eAAe,CAoB3B;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,UATa,OAAO,CAAC,IAAI,CAAC,CA0BzB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAiBD;;;;;;;;;;;;;;;OAeG;IACH,WAZW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAoCpF;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAqBzB;IA8BD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,MAAM,CAclB;IAED;;;;;;;;;;;;;;OAcG;IACH,UARa,OAAO,CAAC,IAAI,CAAC,CAkBzB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAM5B;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAO5B;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,sBAdW,MAAM,GACJ,eAAe,CAoB3B;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,kBAbW,MAAM,GACJ,UAAU,CAkBtB;;CACF;eAnmBc,SAAS;uBACD,iBAAiB"}

package/src/types/lib/TempDirectoryObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TempDirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/TempDirectoryObject.js"],"names":[],"mappings":"AAcA;;;;;;;;;GASG;AACH;IAEE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,mBAxBW,MAAM,OAAC,WACP,mBAAmB,OAAC,EAoF9B;IAsBD;;;;;;;;;;;;;;OAcG;IACH,sBAVW,MAAM,GACJ,mBAAmB,CAY/B;IAED;;;;;;;;;;;;;;OAcG;IACH,kBAVW,MAAM,GACJ,UAAU,CAYtB;;CAUF;kCArLiC,4BAA4B"}
+{"version":3,"file":"TempDirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/TempDirectoryObject.js"],"names":[],"mappings":"AAcA;;;;;;;;;GASG;AACH;IAEE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,mBAxBW,MAAM,OAAC,WACP,mBAAmB,OAAC,EA6F9B;IAsBD;;;;;;;;;;;;;;OAcG;IACH,sBAVW,MAAM,GACJ,mBAAmB,CAY/B;IAED;;;;;;;;;;;;;;OAcG;IACH,kBAVW,MAAM,GACJ,UAAU,CAYtB;;CAUF;kCA9LiC,4BAA4B"}

package/src/lib/Contract.js

@@ -1,256 +0,0 @@
-import Sass from "./Sass.js"
-import Schemer from "./Schemer.js"
-import Data from "../browser/lib/Data.js"
-
-/**
- * Contract represents a successful negotiation between Terms.
- * It handles validation and compatibility checking between what
- * one action provides and what another accepts.
- */
-export default class Contract {
-  #providerTerms = null
-  #consumerTerms = null
-  #validator = null
-  #debug = null
-  #isNegotiated = false
-
-  /**
-   * Creates a contract by negotiating between provider and consumer terms
-   *
-   * @param {import("./Terms.js").Terms} providerTerms - What the provider offers
-   * @param {import("./Terms.js").Terms} consumerTerms - What the consumer expects
-   * @param {object} options - Configuration options
-   * @param {import('../types.js').DebugFunction} [options.debug] - Debug function
-   */
-  constructor(providerTerms, consumerTerms, {debug = null} = {}) {
-    this.#providerTerms = providerTerms
-    this.#consumerTerms = consumerTerms
-    this.#debug = debug
-
-    // Perform the negotiation
-    this.#negotiate()
-  }
-
-  /**
-   * Extracts the actual schema from a terms definition
-   *
-   * @param {object} definition - Terms definition with TLD descriptor
-   * @returns {object} Extracted schema content
-   * @throws {Sass} If definition structure is invalid
-   * @private
-   */
-  static #extractSchemaFromTerms(definition) {
-    // Must be a plain object
-    if(!Data.isPlainObject(definition)) {
-      throw Sass.new("Terms definition must be a plain object")
-    }
-
-    // Must have exactly one key (the TLD/descriptor)
-    const keys = Object.keys(definition)
-    if(keys.length !== 1) {
-      throw Sass.new("Terms definition must have exactly one top-level key (descriptor)")
-    }
-
-    // Extract the content under the TLD
-    const [key] = keys
-
-    return definition[key]
-  }
-
-  /**
-   * Creates a contract from terms with schema validation
-   *
-   * @param {string} name - Contract identifier
-   * @param {object} termsDefinition - The terms definition
-   * @param {import('ajv').ValidateFunction|null} [validator] - Optional AJV schema validator function with .errors property
-   * @param {import('../types.js').DebugFunction} [debug] - Debug function
-   * @returns {Contract} New contract instance
-   */
-  static fromTerms(name, termsDefinition, validator = null, debug = null) {
-    // Validate the terms definition if validator provided
-    if(validator) {
-      const valid = validator(termsDefinition)
-
-      if(!valid) {
-        const error = Schemer.reportValidationErrors(validator.errors)
-        throw Sass.new(`Invalid terms definition for ${name}:\n${error}`)
-      }
-    }
-
-    // Extract schema from terms definition for validation
-    const schemaDefinition = Contract.#extractSchemaFromTerms(termsDefinition)
-    const termsSchemaValidator = Schemer.getValidator(schemaDefinition)
-
-    const contract = new Contract(null, null, {debug})
-    contract.#validator = termsSchemaValidator
-    contract.#isNegotiated = true // Single-party contract is automatically negotiated
-
-    return contract
-  }
-
-  /**
-   * Performs negotiation between provider and consumer terms
-   *
-   * @private
-   */
-  #negotiate() {
-    if(!this.#providerTerms || !this.#consumerTerms) {
-      // Single-party contract scenario
-      this.#isNegotiated = true
-
-      return
-    }
-
-    // Extract content for comparison (ignore TLD metadata)
-    const providerContent = Contract.#extractSchemaFromTerms(
-      this.#providerTerms.definition
-    )
-    const consumerContent = Contract.#extractSchemaFromTerms(
-      this.#consumerTerms.definition
-    )
-
-    // Compare terms for compatibility
-    const compatibility = this.#compareTerms(providerContent, consumerContent)
-
-    if(compatibility.status === "error") {
-      throw Sass.new(
-        `Contract negotiation failed: ${compatibility.errors.map(e => e.message).join(", ")}`
-      )
-    }
-
-    this.#isNegotiated = true
-    this.#debug?.(`Contract negotiated successfully`, 3)
-  }
-
-  /**
-   * Validates data against this contract
-   *
-   * @param {object} data - Data to validate
-   * @returns {boolean} True if valid
-   * @throws {Sass} If validation fails or contract not negotiated
-   */
-  validate(data) {
-    const debug = this.#debug
-
-    if(!this.#isNegotiated)
-      throw Sass.new("Cannot validate against unnegotiated contract")
-
-    if(!this.#validator)
-      throw Sass.new("No validator available for this contract")
-
-    debug?.("Validating data %o", 4, data)
-
-    const valid = this.#validator(data)
-
-    if(!valid) {
-      const error = Schemer.reportValidationErrors(this.#validator.errors)
-      throw Sass.new(`Contract validation failed:\n${error}`)
-    }
-
-    return true
-  }
-
-  /**
-   * Compares terms for compatibility
-   *
-   * @param {object} providerTerms - Terms offered by provider
-   * @param {object} consumerTerms - Terms expected by consumer
-   * @param {Array<string>} stack - Stack trace for nested validation
-   * @returns {object} Result with status and errors
-   * @private
-   */
-  #compareTerms(providerTerms, consumerTerms, stack = []) {
-    const debug = this.#debug
-    const breadcrumb = key => (stack.length ? `@${stack.join(".")}` : key)
-    const errors = []
-
-    if(!providerTerms || !consumerTerms) {
-      return {
-        status: "error",
-        errors: [Sass.new("Both provider and consumer terms are required")]
-      }
-    }
-
-    debug?.("Comparing provider keys:%o with consumer keys:%o", 3,
-      Object.keys(providerTerms), Object.keys(consumerTerms))
-
-    // Check that consumer requirements are met by provider
-    for(const [key, consumerRequirement] of Object.entries(consumerTerms)) {
-      debug?.("Checking consumer requirement: %o [required = %o]", 3,
-        key, consumerRequirement.required ?? false)
-
-      if(consumerRequirement.required && !(key in providerTerms)) {
-        debug?.("Provider missing required capability: %o", 2, key)
-        errors.push(
-          Sass.new(`Provider missing required capability: ${key} ${breadcrumb(key)}`)
-        )
-        continue
-      }
-
-      if(key in providerTerms) {
-        const expectedType = consumerRequirement.dataType
-        const providedType = providerTerms[key]?.dataType
-
-        if(expectedType && providedType && expectedType !== providedType) {
-          errors.push(
-            Sass.new(
-              `Type mismatch for ${key}: Consumer expects ${expectedType}, provider offers ${providedType} ${breadcrumb(key)}`
-            )
-          )
-        }
-
-        // Recursive validation for nested requirements
-        if(consumerRequirement.contains) {
-          debug?.("Recursing into nested requirement: %o", 3, key)
-          const nestedResult = this.#compareTerms(
-            providerTerms[key]?.contains,
-            consumerRequirement.contains,
-            [...stack, key]
-          )
-
-          if(nestedResult.errors.length) {
-            errors.push(...nestedResult.errors)
-          }
-        }
-      }
-    }
-
-    return {status: errors.length === 0 ? "success" : "error", errors}
-  }
-
-  /**
-   * Check if contract negotiation was successful
-   *
-   * @returns {boolean} True if negotiated
-   */
-  get isNegotiated() {
-    return this.#isNegotiated
-  }
-
-  /**
-   * Get the provider terms (if any)
-   *
-   * @returns {import("./Terms.js").default|null} Provider terms
-   */
-  get providerTerms() {
-    return this.#providerTerms
-  }
-
-  /**
-   * Get the consumer terms (if any)
-   *
-   * @returns {import("./Terms.js").default|null} Consumer terms
-   */
-  get consumerTerms() {
-    return this.#consumerTerms
-  }
-
-  /**
-   * Get the contract validator
-   *
-   * @returns {(data: object) => boolean|null} The contract validator function
-   */
-  get validator() {
-    return this.#validator
-  }
-}

package/src/lib/Schemer.js

@@ -1,89 +0,0 @@
-import Ajv from "ajv"
-
-import Data from "../browser/lib/Data.js"
-import Util from "../browser/lib/Util.js"
-import Valid from "./Valid.js"
-
-/**
- * Schemer provides utilities for compiling and validating JSON schemas using AJV.
- *
- * Usage:
- *   - Use Schemer.fromFile(file, options) to create a validator from a file.
- *   - Use Schemer.from(schemaData, options) to create a validator from a schema object.
- *   - Use Schemer.getValidator(schema, options) to get a raw AJV validator function.
- *   - Use Schemer.reportValidationErrors(errors) to format AJV validation errors.
- */
-export default class Schemer {
-  static async fromFile(file, options={}) {
-    Valid.type(file, "FileObject")
-    Valid.assert(Data.isPlainObject(options), "Options must be a plain object.")
-
-    const schemaData = await file.loadData()
-
-    return Schemer.getValidator(schemaData, options)
-  }
-
-  static async from(schemaData={}, options={}) {
-    Valid.assert(Data.isPlainObject(schemaData), "Schema data must be a plain object.")
-    Valid.assert(Data.isPlainObject(options), "Options must be a plain object.")
-
-    return Schemer.getValidator(schemaData, options)
-  }
-
-  /**
-   * Creates a validator function from a schema object
-   *
-   * @param {object} schema - The schema to compile
-   * @param {object} [options] - AJV options
-   * @returns {(data: unknown) => boolean} The AJV validator function, which may have additional properties (e.g., `.errors`)
-   */
-  static getValidator(schema, options = {allErrors: true, verbose: true}) {
-    const ajv = new Ajv(options)
-
-    return ajv.compile(schema)
-  }
-
-  static reportValidationErrors(errors) {
-    if(!errors) {
-      return ""
-    }
-
-    return errors.reduce((errorMessages, error) => {
-      let msg = `- "${error.instancePath || "(root)"}" ${error.message}`
-
-      if(error.params) {
-        const details = []
-
-        if(error.params.type)
-          details.push(`  ➜ Expected type: ${error.params.type}`)
-
-        if(error.params.missingProperty)
-          details.push(`  ➜ Missing required field: ${error.params.missingProperty}`)
-
-        if(error.params.allowedValues) {
-          details.push(`  ➜ Allowed values: "${error.params.allowedValues.join('", "')}"`)
-          details.push(`  ➜ Received value: "${error.data}"`)
-          const closestMatch =
-            Util.findClosestMatch(error.data, error.params.allowedValues)
-
-          if(closestMatch)
-            details.push(`  ➜ Did you mean: "${closestMatch}"?`)
-        }
-
-        if(error.params.pattern)
-          details.push(`  ➜ Expected pattern: ${error.params.pattern}`)
-
-        if(error.params.format)
-          details.push(`  ➜ Expected format: ${error.params.format}`)
-
-        if(error.params.additionalProperty)
-          details.push(`  ➜ Unexpected property: ${error.params.additionalProperty}`)
-
-        if(details.length)
-          msg += `\n${details.join("\n")}`
-      }
-
-      return errorMessages ? `${errorMessages}\n${msg}` : msg
-    }, "")
-  }
-}

package/src/lib/Terms.js

@@ -1,73 +0,0 @@
-import JSON5 from "json5"
-import yaml from "yaml"
-
-import Data from "../browser/lib/Data.js"
-import FileObject from "./FileObject.js"
-import Sass from "./Sass.js"
-import Valid from "./Valid.js"
-
-const refex = /^ref:\/\/(?<file>.*)$/
-
-/**
- * Terms represents an interface definition - what an action promises to provide or accept.
- * It's just the specification, not the negotiation. Contract handles the negotiation.
- */
-export default class Terms {
-  #definition = null
-
-  constructor(definition) {
-    this.#definition = definition
-  }
-
-  /**
-   * Parses terms data, handling file references
-   *
-   * @param {string|object} termsData - Terms data or reference
-   * @param {import("./DirectoryObject.js").DirectoryObject?} directoryObject - Directory context for file resolution
-   * @returns {object} Parsed terms data
-   */
-  static async parse(termsData, directoryObject) {
-    if(Data.isBaseType(termsData, "String")) {
-      const match = refex.exec(termsData)
-
-      if(match?.groups?.file) {
-        Valid.type(directoryObject, "DirectoryObject")
-
-        const file = new FileObject(match.groups.file, directoryObject)
-
-        return await file.loadData()
-      }
-
-      // Try parsing as YAML/JSON
-      try {
-        const result = JSON5.parse(termsData)
-
-        return result
-      } catch {
-        try {
-          const result = yaml.parse(termsData)
-
-          return result
-        } catch {
-          throw Sass.new(`Could not parse terms data as YAML or JSON: ${termsData}`)
-        }
-      }
-    }
-
-    if(Data.isBaseType(termsData, "Object")) {
-      return termsData
-    }
-
-    throw Sass.new(`Invalid terms data type: ${typeof termsData}`)
-  }
-
-  /**
-   * Get the terms definition
-   *
-   * @returns {object} The terms definition
-   */
-  get definition() {
-    return this.#definition
-  }
-
-}

package/src/types/lib/Contract.d.ts

@@ -1,71 +0,0 @@
-/**
- * Contract represents a successful negotiation between Terms.
- * It handles validation and compatibility checking between what
- * one action provides and what another accepts.
- */
-export default class Contract {
-    /**
-     * Extracts the actual schema from a terms definition
-     *
-     * @param {object} definition - Terms definition with TLD descriptor
-     * @returns {object} Extracted schema content
-     * @throws {Sass} If definition structure is invalid
-     * @private
-     */
-    private static "__#private@#extractSchemaFromTerms";
-    /**
-     * Creates a contract from terms with schema validation
-     *
-     * @param {string} name - Contract identifier
-     * @param {object} termsDefinition - The terms definition
-     * @param {import('ajv').ValidateFunction|null} [validator] - Optional AJV schema validator function with .errors property
-     * @param {import('../types.js').DebugFunction} [debug] - Debug function
-     * @returns {Contract} New contract instance
-     */
-    static fromTerms(name: string, termsDefinition: object, validator?: any | null, debug?: any): Contract;
-    /**
-     * Creates a contract by negotiating between provider and consumer terms
-     *
-     * @param {import("./Terms.js").Terms} providerTerms - What the provider offers
-     * @param {import("./Terms.js").Terms} consumerTerms - What the consumer expects
-     * @param {object} options - Configuration options
-     * @param {import('../types.js').DebugFunction} [options.debug] - Debug function
-     */
-    constructor(providerTerms: import("./Terms.js").Terms, consumerTerms: import("./Terms.js").Terms, { debug }?: {
-        debug?: any;
-    });
-    /**
-     * Validates data against this contract
-     *
-     * @param {object} data - Data to validate
-     * @returns {boolean} True if valid
-     * @throws {Sass} If validation fails or contract not negotiated
-     */
-    validate(data: object): boolean;
-    /**
-     * Check if contract negotiation was successful
-     *
-     * @returns {boolean} True if negotiated
-     */
-    get isNegotiated(): boolean;
-    /**
-     * Get the provider terms (if any)
-     *
-     * @returns {import("./Terms.js").default|null} Provider terms
-     */
-    get providerTerms(): import("./Terms.js").default | null;
-    /**
-     * Get the consumer terms (if any)
-     *
-     * @returns {import("./Terms.js").default|null} Consumer terms
-     */
-    get consumerTerms(): import("./Terms.js").default | null;
-    /**
-     * Get the contract validator
-     *
-     * @returns {(data: object) => boolean|null} The contract validator function
-     */
-    get validator(): (data: object) => boolean | null;
-    #private;
-}
-//# sourceMappingURL=Contract.d.ts.map

package/src/types/lib/Contract.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Contract.d.ts","sourceRoot":"","sources":["../../lib/Contract.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IAwBE;;;;;;;OAOG;IACH,oDAgBC;IAED;;;;;;;;OAQG;IACH,uBANW,MAAM,mBACN,MAAM,cACN,GAA8B,GAAC,IAAI,gBAEjC,QAAQ,CAsBpB;IAxED;;;;;;;OAOG;IACH,2BALW,OAAO,YAAY,EAAE,KAAK,iBAC1B,OAAO,YAAY,EAAE,KAAK,cAElC;QAAsD,KAAK,GAAnD,GAAmC;KAC7C,EAQA;IA6FD;;;;;;OAMG;IACH,eAJW,MAAM,GACJ,OAAO,CAsBnB;IAsED;;;;OAIG;IACH,oBAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,qBAFa,OAAO,YAAY,EAAE,OAAO,GAAC,IAAI,CAI7C;IAED;;;;OAIG;IACH,qBAFa,OAAO,YAAY,EAAE,OAAO,GAAC,IAAI,CAI7C;IAED;;;;OAIG;IACH,iBAFa,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAC,IAAI,CAI1C;;CACF"}

package/src/types/lib/Schemer.d.ts

@@ -1,23 +0,0 @@
-/**
- * Schemer provides utilities for compiling and validating JSON schemas using AJV.
- *
- * Usage:
- *   - Use Schemer.fromFile(file, options) to create a validator from a file.
- *   - Use Schemer.from(schemaData, options) to create a validator from a schema object.
- *   - Use Schemer.getValidator(schema, options) to get a raw AJV validator function.
- *   - Use Schemer.reportValidationErrors(errors) to format AJV validation errors.
- */
-export default class Schemer {
-    static fromFile(file: any, options?: {}): Promise<(data: unknown) => boolean>;
-    static from(schemaData?: {}, options?: {}): Promise<(data: unknown) => boolean>;
-    /**
-     * Creates a validator function from a schema object
-     *
-     * @param {object} schema - The schema to compile
-     * @param {object} [options] - AJV options
-     * @returns {(data: unknown) => boolean} The AJV validator function, which may have additional properties (e.g., `.errors`)
-     */
-    static getValidator(schema: object, options?: object): (data: unknown) => boolean;
-    static reportValidationErrors(errors: any): any;
-}
-//# sourceMappingURL=Schemer.d.ts.map

package/src/types/lib/Schemer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Schemer.d.ts","sourceRoot":"","sources":["../../lib/Schemer.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AACH;IACE,yDAqBoB,OAAO,KAAK,OAAO,EAdtC;IAED,2DAYoB,OAAO,KAAK,OAAO,EAPtC;IAED;;;;;;OAMG;IACH,4BAJW,MAAM,YACN,MAAM,GACJ,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAMtC;IAED,gDA0CC;CACF"}

package/src/types/lib/Terms.d.ts

@@ -1,23 +0,0 @@
-/**
- * Terms represents an interface definition - what an action promises to provide or accept.
- * It's just the specification, not the negotiation. Contract handles the negotiation.
- */
-export default class Terms {
-    /**
-     * Parses terms data, handling file references
-     *
-     * @param {string|object} termsData - Terms data or reference
-     * @param {import("./DirectoryObject.js").DirectoryObject?} directoryObject - Directory context for file resolution
-     * @returns {object} Parsed terms data
-     */
-    static parse(termsData: string | object, directoryObject: import("./DirectoryObject.js").DirectoryObject | null): object;
-    constructor(definition: any);
-    /**
-     * Get the terms definition
-     *
-     * @returns {object} The terms definition
-     */
-    get definition(): object;
-    #private;
-}
-//# sourceMappingURL=Terms.d.ts.map

package/src/types/lib/Terms.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Terms.d.ts","sourceRoot":"","sources":["../../lib/Terms.js"],"names":[],"mappings":"AAUA;;;GAGG;AACH;IAOE;;;;;;OAMG;IACH,wBAJW,MAAM,GAAC,MAAM,mBACb,OAAO,sBAAsB,EAAE,eAAe,OAAC,GAC7C,MAAM,CAmClB;IA5CD,6BAEC;IA4CD;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;;CAEF"}