@stless/modify-js 1.0.0 → 1.1.0

package/README.md

@@ -7,17 +7,37 @@
 # @stless/modify-js
 
 [![npm version](https://img.shields.io/npm/v/@stless/modify-js.svg)](https://www.npmjs.com/package/@stless/modify-js)
-![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-green)
+![Node.js](https://img.shields.io/badge/Node.js-%3E%3D16.11.0-green)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/harnuma9/modify-js/blob/main/LICENSE)
 ![Verify Status](https://github.com/harnuma9/modify-js/actions/workflows/verify.yml/badge.svg)
-[![Socket Badge](https://badge.socket.dev/npm/package/@stless/modify-js/1.0.0)](https://badge.socket.dev/npm/package/@stless/modify-js/1.0.0)
+[![Socket Badge](https://badge.socket.dev/npm/package/@stless/modify-js/1.1.0)](https://badge.socket.dev/npm/package/@stless/modify-js/1.1.0)
 [![Donate](https://img.shields.io/badge/@Harnuma9-Donate-FF4D4D)](https://harnuma9.github.io/donate/)
 
 <br />
 
-**Lightweight functional chaining for JavaScript.**
-`modify-js` is a zero-dependency utility that provides a user-land polyfill for the proposed **[TC39](https://github.com/tc39/proposal-pipeline-operator) Pipeline Operator**.
-It safely extends native prototypes, and it allows you to transform data through readable, linear pipelines without the syntactic “callback hell” of nested functions.
+`@stless/modify-js` is a lightweight, zero-dependency utility that brings functional piping to JavaScript. It provides a secure, high-performance alternative to the proposed **[TC39 Pipeline Operator](https://github.com/tc39/proposal-pipeline-operator)**.
+
+Values wrapped in a “Hardened Pipe” can transform data through readable, linear pipelines. This eliminates the “Callback Hell” of nested functions and ensures your data remains encapsulated and secure throughout its lifecycle.
+
+<br />
+
+---
+
+<br />
+
+## ✨ Why `[modify](JS)`?
+
+While standard JavaScript requires nested function calls or intermediate variables, [modify-js](https://www.npmjs.com/package/@stless/modify-js) allows for a clean, top-down data flow.
+
+<br />
+
+* **🔒 Hardened Security**: Uses **[ES2022 Private Class Fields](https://dev.to/smitterhane/private-class-fields-in-javascript-es2022-3b8)** (`#value`) to keep your data invisible to external scripts and loggers.
+
+* **🧼 Auto-Sanitization**: Optionally wipes internal state and freezes the pipe instance upon exit.
+
+* **🎯 Zero Side-Effects**: This version does not touch native prototypes or lead to syntax errors, making it 100% safe for production environments and compatible for modern use.
+
+* **⚡ High Performance**: Optimized for the V8 engine with a single-allocation design that is friendly to the Garbage Collector.
 
 <br />
 
@@ -50,6 +70,14 @@ yarn add @stless/modify-js
 pnpm add @stless/modify-js
 ```
 
+<br />
+
+### Requirements
+
+* **Node.js**: `>=16.11.0` (For stable [ES2022 Private Field](https://dev.to/smitterhane/private-class-fields-in-javascript-es2022-3b8) support)
+
+* **Browser**: Modern evergreen browsers (Chrome 91+, Firefox 90+, Safari 15+)
+
 <br />
 <br />
 
@@ -59,20 +87,19 @@ pnpm add @stless/modify-js
 
 ### Initialize the Environment
 
-`modify-js` follows the [Principle of Least Power](https://en.wikipedia.org/wiki/Rule_of_least_power). It does not patch anything until you tell it to. Use `discover()` to find all global constructors (Array, String, Map, URL, etc.) or pass an explicit list.
+Use `chain_` (or the shorthand `chain$`) to start a pipeline. The data is immediately encapsulated in a private class field.
 
 ```javascript
 // ESM
-import applyModify, { discover, __F0V0 } from '@stless/modify-js';
+import chain_ from '@stless/modify-js';
 // or CJS
-const { default: applyModify, discover, __F0V0 } = require('@stless/modify-js');
+const { default: chain_, chain$ } = require('@stless/modify-js');
 
 
-// Option A: Explicit injection
-applyModify([String, Array, Promise]);
-
-// Option B: Global discovery and silent injection
-applyModify(discover(), __F0V0);
+const result = chain_("  hello world  ")
+  ._p(s => s.trim())
+  .$p(s => s.toUpperCase())
+  .out(); // "HELLO WORLD"
 ```
 
 <br />
@@ -82,56 +109,55 @@ applyModify(discover(), __F0V0);
 Transform data from left-to-right. Use `._p()`, `.$p()`, or `.modify()` to chain functions.
 
 ```javascript
-const result = "  hello world  "
-  ._p(s => s.trim())
-  ._p(s => s.toUpperCase())
-  ._p(s => s + "!!!")
-  .out();
-
-console.log(result); // "HELLO WORLD!!!"
+const user = chain$(apiResponse)
+  ._p(res => res.data)
+  ._p(data => ({ ...data, timestamp: Date.now() }))
+  .out({ error: "No data found" }); // Safe fallback
 ```
 
 <br />
 
-### Tapping Mid-chain
+### Tapping & Side Effects
 
-You can also “tap” into the pipe, mid-chain without interruption.
+You can “tap” into the pipe mid-chain for logging or cleanup without breaking the flow.
 
 ```javascript
-const result = "100"
-  ._p(s => parseInt(s, 10))
-  ._p(n => Math.pow(n, 2))
-  ._p(u => (console.log(u), u)) // console and return the same value
-  ._p(v => ({ value: v }))
-  .out();
-```
+const a = chain$(100)
+  ._p(n => n * 2)
+  // log then return value
+  ._p(v => (console.log(`Value is: ${v}`), v));
 
-<br />
+const val1 = a.out(null, false); // set to false
 
-### Standalone Chaining (No Prototype Pollution)
+// Reuse the same chain
+const val2 = a
+  .modify(n => n - 20)
+  .out(null, true); // lock the pipe
 
-If you prefer not to touch native prototypes, use `chain_` (or shorthand `chain$`) to wrap values manually.
-
-```javascript
-import { chain$ } from '@stless/modify-js';
-
-const val = chain$("data")
-  .$p(d => d.split(""))
-  .out();
+console.log(val1); // Output: 200
+console.log(val2); // Output: 180
 ```
 
 <br />
 
-### Restore the Environment
+### The “Security Exit”
 
-You can completely remove `modify-js` from the environment at runtime.
+The `.out()` method is the most powerful part of the library. It **handles extraction and cleanup** simultaneously.
 
 ```javascript
-import { ejectModify } from '@stless/modify-js';
+// Default:
+// .out(fallbackValue, shouldLock=true)
 
-ejectModify({ verbose: true }); // Restores all prototypes to factory state
+const data = pipe.out("Unknown", true);
+console.log(pipe.isLocked());           // Output: true
 ```
 
+* **Defaulting**: If the pipe resulted in `null` or `undefined`, it returns your default.
+
+* **Wiping**: It clears the internal private state.
+
+* **Locking**: It freezes the pipe object, making it impossible to reuse or hijack.
+
 <br />
 
 ### Shortcut one-liner
@@ -140,15 +166,13 @@ It is possible to achieve a functional code with almost no `const`, `let`, or `v
 
 <br />
 
-**Before:**
+**Before (Imperative):**
 
 ```javascript
 function encryptMsg(algo, data, key, iv) {
   const cipher = crypto.createCipheriv(algo, key, iv);
-  const part1 = cipher.update(data);
-  const part2 = cipher.final();
-  const encrypted = Buffer.concat([part1, part2]);
-  key.fill(0);
+  const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
+  key.fill(0); // Sensitive cleanup
   iv.fill(0);
   return encrypted;
 }
@@ -156,11 +180,11 @@ function encryptMsg(algo, data, key, iv) {
 
 <br />
 
-**After (Modify-JS applied):**
+**After (With Hardened Pipe):**
 
 ```javascript
 function encryptMsg(algo, data, key, iv) {
-  return [algo, key, iv]
+  return chain_([algo, key, iv])
     ._p(a => crypto.createCipheriv(...a))                // Create cipher
     ._p(c => Buffer.concat([c.update(data), c.final()])) // Process data
     ._p(enc => (key.fill(0), iv.fill(0), enc))           // Cleanup & return
@@ -184,64 +208,6 @@ function encryptMsg(algo, data, key, iv) {
 <br />
 <br />
 
-## Advanced Injection Options
-
-Control how `modify-js` handles collisions with existing methods using pre-defined shorthand constants:
-
-| Constant     | Force        | Verbose      | Description  |
-|--------------|--------------|--------------|--------------|
-|`__F0V1`      | `false`      | `true`       | **Standard:** Only patch new methods, log collisions. |
-|`__F1V1`      | `true`       | `true`       | **Debug:** Overwrite everything and log actions. |
-|`__F0V0`      | `false`      | `false`      | **Silent:** Patch if possible, no logs. |
-|`__F1V0`      | `true`       | `false`      | **Override:** Overwrite everything silently. |
-
-<br />
-<br />
-
-## 🔩 API Reference
-
-<br />
-
-### `applyModify(targets, options)`
-
-Injects pipeline methods into prototype chains.
-
-* `targets`: `Array<Function>` - List of constructors (e.g. `[String, Array]`).
-* `options`: `ModifyOptions` - `{ force: boolean, verbose: boolean }`.
-
-<br />
-
-### `discover()`
-
-Reflectively scans `globalThis` for all [PascalCase](https://convertcase.help/blog/what-is-pascalcase/) functions with prototypes. Includes `Buffer` in Node environments.
-
-<br />
-
-### `hasBeenApplied()`
-
-Returns a `boolean` indicating if the library has been initialized. Useful for conditional logic in environments with [hot-module reloading (HMR)](https://webpack.js.org/guides/hot-module-replacement/) or complex entry points.
-
-<br />
-
-### `getAppliedTargets()`
-
-Returns an `Array` of all currently patched constructors. This provides full transparency into what native objects have been modified by the library.
-
-<br />
-
-### `chain_(val)` / `chain$(val)`
-
-Wraps a value in a `ChainBox` for processing without prototype extensions.
-
-<br />
-
-### `ejectModify(options)`
-
-Reverses all changes made by `applyModify` and resets internal library state.
-
-<br />
-<br />
-
 ---
 
 <br />

package/dist/index.min.js

@@ -1,9 +1,8 @@
 /**
- * @file Prototype extension utility for functional chaining.
- * @summary A user-land polyfill for the proposed TC39 Pipeline Operator.
+ * @file Optimized utility for functional chaining and data transformation.
+ * @summary Lightweight, high-performance, zero-dependency, hardened polyfill for the TC39 Pipeline Operator.
  * @author Aries Harbinger
  * @license Apache-2.0
- * @module modify-js
  */
-const appliedTargets=new Set;let isApplied=!1;export const __F0V0={force:!1,verbose:!1};export const __F1V1={force:!0,verbose:!0};export const __F0V1={force:!1,verbose:!0};export const __F1V0={force:!0,verbose:!1};export const hasBeenApplied=()=>isApplied;export const getAppliedTargets=()=>Array.from(appliedTargets);export function discover(){const e=Object.getOwnPropertyNames(globalThis).filter(e=>{try{const o=globalThis[e];return/^[A-Z]/.test(e)&&"function"==typeof o&&o.prototype}catch(e){return!1}}).map(e=>globalThis[e]);return"undefined"==typeof Buffer||e.includes(Buffer)||e.push(Buffer),e}export const chain_=e=>{const o=e=>chain_(e);return Object.freeze({modify:t=>o(t(e)),_p:t=>o(t(e)),$p:t=>o(t(e)),out:o=>null==e?o:e})};export const chain$=chain_;const modifyDefinition=Object.freeze({enumerable:!1,configurable:!0,writable:!0,value:function(e){if("function"!=typeof e)throw new TypeError("Expected a function");return chain_(e(this))}});export function ejectModify({verbose:e=!0}={}){getAppliedTargets().forEach(o=>{try{const e=o.prototype;delete e.modify,delete e._p,delete e.$p,appliedTargets.delete(o)}catch(t){e&&console.warn(`[modify-js] Skipping ${o.name||"Anonymous"}: Unable to eject. Reason: ${t.message}`)}}),appliedTargets.size<=0&&(e&&console.log("[modify-js] Environment fully restored."),isApplied=!1)}export function applyModify(e=[],{force:o=!1,verbose:t=!0}={}){if(!(isApplied&&!o&&e.length<=0)){if(!Array.isArray(e))throw new Error("applyModify requires an array of constructors. Use discover() to get all available.");e.forEach(e=>{if(appliedTargets.has(e)&&!o)return;const r=e?.prototype;if(!r)return void(t&&console.warn(`[modify-js] Skipping ${e}: No prototype available.`));["modify","_p","$p"].forEach(n=>{if(!Object.prototype.hasOwnProperty.call(r,n)||o)try{Object.defineProperty(r,n,modifyDefinition)}catch(o){t&&console.warn(`[modify-js] Skipping ${e.name||"Anonymous"}: Unable to inject .${n}(). Reason: ${o.message}`)}else t&&console.warn(`[modify-js] Skipping ${e.name||"Anonymous"}: .${n}() already exists.`)}),appliedTargets.add(e)}),isApplied=!0}}export default applyModify;
+export class Pipe{#t;constructor(t){this.#t=t}modify(t){return this.#t=t(this.#t),this}_p(t){return this.modify(t)}$p(t){return this.modify(t)}out(t,e=!0){try{return null==this.#t?t:this.#t}finally{e&&(this.#t=null,Object.freeze(this))}}_o(t,e){return this.out(t,e)}$o(t,e){return this.out(t,e)}isLocked(){return Object.isFrozen(this)}_l(){return this.isLocked()}$l(){return this.isLocked()}}export const chain_=t=>new Pipe(t);export const chain$=t=>new Pipe(t);export default chain_;
 //# sourceMappingURL=index.min.js.map

package/dist/index.min.js.map

@@ -1 +1 @@
-{"version":3,"file":"dist/index.min.js.map","names":["appliedTargets","Set","isApplied","__F0V0","force","verbose","__F1V1","__F0V1","__F1V0","hasBeenApplied","getAppliedTargets","Array","from","discover","selection","Object","getOwnPropertyNames","globalThis","filter","name","item","test","prototype","_","map","Buffer","includes","push","chain_","val","inner","v","freeze","modify","fn","_p","$p","out","def","chain$","modifyDefinition","enumerable","configurable","writable","value","TypeError","this","ejectModify","forEach","target","proto","delete","e","console","warn","message","size","log","applyModify","targets","length","isArray","Error","has","methodName","hasOwnProperty","call","defineProperty","add"],"sources":["src/index.js"],"mappings":";;;;;;;AA8BA,MAAMA,eAAiB,IAAIC,IAO3B,IAAIC,WAAY,SAcT,MAAMC,OAAS,CAAEC,OAAO,EAAOC,SAAS,UAMxC,MAAMC,OAAS,CAAEF,OAAO,EAAOC,SAAS,UAMxC,MAAME,OAAS,CAAEH,OAAO,EAAOC,SAAS,UAMxC,MAAMG,OAAS,CAAEJ,OAAO,EAAOC,SAAS,UAQxC,MAAMI,eAAiB,IAAMP,iBAQ7B,MAAMQ,kBAAoB,IAAMC,MAAMC,KAAKZ,uBAS3C,SAASa,WACd,MAAMC,EAAYC,OAAOC,oBAAoBC,YAC1CC,OAAOC,IACN,IACE,MAAMC,EAAOH,WAAWE,GAExB,MAAO,SAASE,KAAKF,IACK,mBAATC,GACPA,EAAKE,SACjB,CAEA,MAAOC,GAAK,OAAO,CAAO,IAE3BC,IAAIL,GAAQF,WAAWE,IAM1B,MAHsB,oBAAXM,QAA2BX,EAAUY,SAASD,SACvDX,EAAUa,KAAKF,QAEVX,CACT,QAwBO,MAAMc,OAAUC,IAErB,MAAMC,EAASC,GAAMH,OAAOG,GAE5B,OAAOhB,OAAOiB,OAAO,CAOnBC,OAASC,GAAOJ,EAAMI,EAAGL,IAQzBM,GAAKD,GAAOJ,EAAMI,EAAGL,IAQrBO,GAAKF,GAAOJ,EAAMI,EAAGL,IAQrBQ,IAAMC,GAAgB,MAAPT,EAAcS,EAAMT,YAShC,MAAMU,OAAgBX,OAe7B,MAAMY,iBAAmBzB,OAAOiB,OAAO,CAErCS,YAAY,EAGZC,cAAc,EAGdC,UAAU,EAOVC,MACS,SAASV,GACd,GAAkB,mBAAPA,EAAmB,MAAM,IAAIW,UAAU,uBAGlD,OAAOjB,OAAOM,EAAGY,MACnB,WAiBG,SAASC,aAAY1C,QAAEA,GAAU,GAAS,CAAC,GAEhCK,oBAERsC,QAAQC,IACd,IACE,MAAMC,EAAQD,EAAO3B,iBAId4B,EAAMjB,cACNiB,EAAMf,UACNe,EAAMd,GAGbpC,eAAemD,OAAOF,EACxB,CAEA,MAAOG,GACD/C,GACFgD,QAAQC,KACN,wBAAwBL,EAAO9B,MAAQ,yCACXiC,EAAEG,UAEpC,IAIEvD,eAAewD,MAAQ,IACrBnD,GACFgD,QAAQI,IAAI,2CACdvD,WAAY,EAEhB,QA0BO,SAASwD,YAAYC,EAAU,IAAIvD,MAAEA,GAAQ,EAAKC,QAAEA,GAAU,GAAS,CAAC,GAE7E,KAAIH,YAAcE,GAASuD,EAAQC,QAAU,GAA7C,CAEA,IAAKjD,MAAMkD,QAAQF,GACjB,MAAM,IAAIG,MAAM,uFAElBH,EAAQX,QAAQC,IAEd,GAAIjD,eAAe+D,IAAId,KAAY7C,EAAO,OAE1C,MAAM8C,EAAQD,GAAQ3B,UAGtB,IAAK4B,EAEH,YADI7C,GAASgD,QAAQC,KAAK,wBAAwBL,+BAIpC,CAAC,SAAU,KAAM,MAEzBD,QAAQgB,IAGd,IAFejD,OAAOO,UAAU2C,eAAeC,KAAKhB,EAAOc,IAE5C5D,EACb,IACEW,OAAOoD,eAAejB,EAAOc,EAAYxB,iBAC3C,CACA,MAAOY,GACD/C,GACFgD,QAAQC,KACN,wBAAwBL,EAAO9B,MAAQ,kCAClB6C,gBAAyBZ,EAAEG,UAEtD,MAESlD,GACTgD,QAAQC,KAAK,wBAAwBL,EAAO9B,MAAQ,iBAAiB6C,yBAIzEhE,eAAeoE,IAAInB,KAGrB/C,WAAY,CA1C0C,CA2CxD,gBAEewD","ignoreList":[]}
+{"version":3,"file":"dist/index.min.js.map","names":["Pipe","value","constructor","val","this","modify","fn","_p","$p","out","def","lock","Object","freeze","_o","$o","isLocked","isFrozen","_l","$l","chain_","chain$"],"sources":["src/index.js"],"mappings":";;;;;;OAkCO,MAAMA,KAMTC,GAMA,WAAAC,CAAYC,GAAOC,MAAKH,EAASE,CAAK,CAUtC,MAAAE,CAAOC,GAEH,OADAF,MAAKH,EAASK,EAAGF,MAAKH,GACfG,IACX,CAOA,EAAAG,CAAGD,GAAM,OAAOF,KAAKC,OAAOC,EAAK,CAOjC,EAAAE,CAAGF,GAAM,OAAOF,KAAKC,OAAOC,EAAK,CAWjC,GAAAG,CAAIC,EAAKC,GAAO,GACZ,IACI,OAAsB,MAAfP,MAAKH,EACNS,EACAN,MAAKH,CAEf,CAAE,QACMU,IACAP,MAAKH,EAAS,KACdW,OAAOC,OAAOT,MAEtB,CACJ,CAQA,EAAAU,CAAGJ,EAAKC,GAAQ,OAAOP,KAAKK,IAAIC,EAAKC,EAAO,CAQ5C,EAAAI,CAAGL,EAAKC,GAAQ,OAAOP,KAAKK,IAAIC,EAAKC,EAAO,CAS5C,QAAAK,GAAa,OAAOJ,OAAOK,SAASb,KAAO,CAG3C,EAAAc,GAAO,OAAOd,KAAKY,UAAY,CAG/B,EAAAG,GAAO,OAAOf,KAAKY,UAAY,SAc5B,MAAMI,OAAUjB,GAAQ,IAAIH,KAAKG,UAQjC,MAAMkB,OAAUlB,GAAQ,IAAIH,KAAKG,kBAEzBiB","ignoreList":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stless/modify-js",
-  "version": "1.0.0",
-  "description": "A zero-dependency prototype extension utility for functional chaining and null-safe pipelines.",
+  "version": "1.1.0",
+  "description": "Lightweight, high-performance, zero-dependency, hardened polyfill for the TC39 Pipeline Operator.",
   "author": "Aries Harbinger",
   "license": "Apache-2.0",
   "homepage": "https://github.com/harnuma9/modify-js#readme",
@@ -28,7 +28,7 @@
     }
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=16.11.0"
   },
   "scripts": {
     "build": "bash update.sh",
@@ -39,10 +39,12 @@
   },
   "keywords": [
     "pipeline",
+    "lightweight",
     "functional",
     "chaining",
     "utility",
-    "prototype",
+    "polyfill",
+    "hardened",
     "tc39",
     "fluent-interface"
   ],

package/src/index.d.ts

@@ -1,110 +1,100 @@
 /**
- * Utility: Scans the global environment for valid constructors with prototypes.
- * This identifies native objects (Array, String, Map, etc.) available for patching.
- * @function discover
- * @returns {Array<Function>} A list of discoverable global constructors.
- */
-export function discover(): Array<Function>;
-/**
- * Removes .modify() and shorthand pipeline methods from all patched constructors.
- * This restores the environment to its original state by deleting the injected
- * prototype properties.
- * @function ejectModify
- * @memberof module:modify-js
- * @param {ModifyOptions} [options={}] - Configuration for the ejection process.
- * @param {boolean} [options.verbose=true] - If true, logs restoration status and warnings.
- * @returns {void}
- * @example
- * ejectModify({ verbose: false }); // Clean up the prototypes
- */
-export function ejectModify({ verbose }?: ModifyOptions): void;
-/**
- * Injects .modify() and shorthands into specified prototype chains.
- * Follows the Principle of Least Power; it does not patch globally
- * unless explicitly passed the results of {@link module:modify-js.discover}.
- * These methods return a {@link ChainBox} to ensure subsequent calls are null-safe.
+ * Copyright 2026 Aries Harbinger
  *
- * @function applyModify
- * @example
- * // Manual explicit injection
- * applyModify([Array, String, Boolean]);
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
  *
- * @example
- * // Intentional global injection
- * applyModify(discover(), __F0V0);
+ * http://www.apache.org/licenses/LICENSE-2.0
  *
- * @example
- * // Usage in code
- * "hello"._p(s => s.toUpperCase()).modify(s => s + "!!!").out(); // "HELLO!!!"
- *
- * @param {Array<Function>} [targets=[]] - An array of constructors to patch.
- * @param {ModifyOptions} [options={}] - Configuration for injection behavior.
- * @returns {void}
- */
-export function applyModify(targets?: Array<Function>, { force, verbose }?: ModifyOptions): void;
-/**
- * Configuration options for injection behavior.
- * @typedef {Object} ModifyOptions
- * @property {boolean} [force=false] - If true, overwrites existing .modify() or shorthand methods.
- * @property {boolean} [verbose=true] - If true, logs warnings when collisions occur.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
  */
 /**
- * Shorthand: Force=False, Verbose=False (Silent Mode)
- * @type {ModifyOptions}
+ * @file Optimized utility for functional chaining and data transformation.
+ * @summary Lightweight, high-performance, zero-dependency, hardened polyfill for the TC39 Pipeline Operator.
+ * @author Aries Harbinger
+ * @license Apache-2.0
  */
-export const __F0V0: ModifyOptions;
 /**
- * Shorthand: Force=True, Verbose=True (Debug/Aggressive Mode)
- * @type {ModifyOptions}
+ * A transformation function used within the pipeline.
+ * @callback ModifyCallback
+ * @param {any} value - The current value in the pipeline.
+ * @returns {any} The transformed value.
  */
-export const __F1V1: ModifyOptions;
 /**
- * Shorthand: Force=False, Verbose=True (Standard Mode)
- * @type {ModifyOptions}
+ * Represents a secure, stateful container for functional transformations.
+ * @class Pipe
  */
-export const __F0V1: ModifyOptions;
-/**
- * Shorthand: Force=True, Verbose=False (Override Mode)
- * @type {ModifyOptions}
- */
-export const __F1V0: ModifyOptions;
-export function hasBeenApplied(): boolean;
-export function getAppliedTargets(): Array<Function>;
-export function chain_(val: any): ChainBox;
-export function chain$(val: any): ChainBox;
-export default applyModify;
-/**
- * Configuration options for injection behavior.
- */
-export type ModifyOptions = {
+export class Pipe {
+    /**
+     * Creates an instance of Pipe.
+     * @param {any} val - The initial value to wrap.
+     */
+    constructor(val: any);
+    /**
+     * Passes the internal value through a transformation function.
+     * Updates the internal state and returns the same Pipe instance.
+     * @method modify
+     * @param {ModifyCallback} fn - The transformation function to execute.
+     * @returns {this} The current Pipe instance for further chaining.
+     */
+    modify(fn: ModifyCallback): this;
     /**
-     * - If true, overwrites existing .modify() or shorthand methods.
+     * Alias for {@link modify}.
+     * @param {ModifyCallback} fn
+     * @returns {this}
      */
-    force?: boolean | undefined;
+    _p(fn: ModifyCallback): this;
     /**
-     * - If true, logs warnings when collisions occur.
+     * Alias for {@link modify}.
+     * @param {ModifyCallback} fn
+     * @returns {this}
      */
-    verbose?: boolean | undefined;
-};
-export type ChainBox = {
+    $p(fn: ModifyCallback): this;
     /**
-     * - Shorthand pipeline method.
+     * Extracts the value from the pipe and terminates the chain.
+     * If the internal value is null or undefined, the provided default is returned.
+     * @method out
+     * @param {any} [def] - Optional fallback value if the pipe's value is null/undefined.
+     * @param {boolean} [lock=true] - If true, wipes the internal state and freezes the object.
+     * @returns {any} The final transformed value or the default fallback.
      */
-    _p: (arg0: ModifyCallback) => ChainBox;
+    out(def?: any, lock?: boolean): any;
     /**
-     * - Shorthand pipeline method.
+     * Alias for {@link out}.
+     * @param {any} [def]
+     * @param {boolean} [lock=true]
+     * @returns {any}
      */
-    $p: (arg0: ModifyCallback) => ChainBox;
+    _o(def?: any, lock?: boolean): any;
     /**
-     * - Explicit pipeline method.
+     * Alias for {@link out}.
+     * @param {any} [def]
+     * @param {boolean} [lock=true]
+     * @returns {any}
      */
-    modify: (arg0: ModifyCallback) => ChainBox;
+    $o(def?: any, lock?: boolean): any;
     /**
-     * - Unwraps the value and exits the chain.
+     * Checks if the pipe instance has been locked and frozen.
+     * A locked pipe can no longer be modified or used to extract values.
+     * @method isLocked
+     * @returns {boolean} True if the instance is frozen, false otherwise.
      */
-    out: (arg0: any | undefined) => any;
-};
+    isLocked(): boolean;
+    /** Alias for {@link isLocked} */
+    _l(): boolean;
+    /** Alias for {@link isLocked} */
+    $l(): boolean;
+    #private;
+}
+export function chain_(val: any): Pipe;
+export function chain$(val: any): Pipe;
+export default chain_;
 /**
- * The transformation callback passed to .modify() or shorthands.
+ * A transformation function used within the pipeline.
  */
-export type ModifyCallback = (instance: any) => any;
+export type ModifyCallback = (value: any) => any;

package/src/index.js

@@ -15,328 +15,138 @@
  */
 
 /**
- * @file Prototype extension utility for functional chaining.
- * @summary A user-land polyfill for the proposed TC39 Pipeline Operator.
+ * @file Optimized utility for functional chaining and data transformation.
+ * @summary Lightweight, high-performance, zero-dependency, hardened polyfill for the TC39 Pipeline Operator.
  * @author Aries Harbinger
  * @license Apache-2.0
- * @module modify-js
  */
 
-
-/**
- * Internal state to track patched constructors.
- * @type {Set<Function>}
- * @private
- */
-const appliedTargets = new Set();
-
-/**
- * Internal state to track if the utility has been initialized at least once.
- * @type {boolean}
- * @private
- */
-let isApplied = false;
-
-
-/**
- * Configuration options for injection behavior.
- * @typedef {Object} ModifyOptions
- * @property {boolean} [force=false] - If true, overwrites existing .modify() or shorthand methods.
- * @property {boolean} [verbose=true] - If true, logs warnings when collisions occur.
- */
-
-/** 
- * Shorthand: Force=False, Verbose=False (Silent Mode) 
- * @type {ModifyOptions}
- */
-export const __F0V0 = { force: false, verbose: false };
-
-/** 
- * Shorthand: Force=True, Verbose=True (Debug/Aggressive Mode) 
- * @type {ModifyOptions}
- */
-export const __F1V1 = { force: true,  verbose: true  };
-
-/** 
- * Shorthand: Force=False, Verbose=True (Standard Mode) 
- * @type {ModifyOptions}
- */
-export const __F0V1 = { force: false, verbose: true  };
-
-/** 
- * Shorthand: Force=True, Verbose=False (Override Mode) 
- * @type {ModifyOptions}
- */
-export const __F1V0 = { force: true,  verbose: false };
-
-
-/**
- * Utility: Checks if the library has been executed at least once.
- * @function hasBeenApplied
- * @returns {boolean} True if applyModify has been called successfully.
- */
-export const hasBeenApplied = () => isApplied;
-
-
 /**
- * Utility: Returns an array of all currently patched constructors.
- * @function getAppliedTargets
- * @returns {Array<Function>} An array containing the constructors currently modified.
+ * A transformation function used within the pipeline.
+ * @callback ModifyCallback
+ * @param {any} value - The current value in the pipeline.
+ * @returns {any} The transformed value.
  */
-export const getAppliedTargets = () => Array.from(appliedTargets);
-
 
 /**
- * Utility: Scans the global environment for valid constructors with prototypes.
- * This identifies native objects (Array, String, Map, etc.) available for patching.
- * @function discover
- * @returns {Array<Function>} A list of discoverable global constructors.
+ * Represents a secure, stateful container for functional transformations.
+ * @class Pipe
  */
-export function discover() {
-  const selection = Object.getOwnPropertyNames(globalThis)
-    .filter(name => {
-      try {
-        const item = globalThis[name];
-        // Filter for PascalCase functions that have a prototype (standard JS classes)
-        return /^[A-Z]/.test(name) 
-               && typeof item === 'function' 
-               && item.prototype;
-      }
-
-      catch (_) { return false; }
-    })
-    .map(name => globalThis[name]);
-
-  // Include Buffer if in a Node-like environment
-  if (typeof Buffer !== 'undefined' && !selection.includes(Buffer))
-    selection.push(Buffer);
-
-  return selection;
-}
-
+export class Pipe {
+    /**
+     * The internal value held by the pipe.
+     * @type {any}
+     * @private
+     */
+    #value;
 
-/**
- * @typedef {Object} ChainBox
- * @property {function(ModifyCallback): ChainBox} _p - Shorthand pipeline method.
- * @property {function(ModifyCallback): ChainBox} $p - Shorthand pipeline method.
- * @property {function(ModifyCallback): ChainBox} modify - Explicit pipeline method.
- * @property {function(any=): any} out - Unwraps the value and exits the chain.
- */
+    /**
+     * Creates an instance of Pipe.
+     * @param {any} val - The initial value to wrap.
+     */
+    constructor(val) { this.#value = val; }
 
-/**
- * A safe wrapper for functional chaining that handles null/undefined values.
- * Once inside a chain_, all subsequent calls are null-safe.
- * @function chain_
- * @param {any} val - The initial value to wrap.
- * @returns {ChainBox} A chainable object containing transformation methods.
- * @example
- * const result = chain_("  hello  ")
- *   .$p(s => s.trim())
- *   .$p(s => null)            // Pipeline continues safely
- *   .$p(s => console.log(s))  // Output mid-chain
- *   .out("DEFAULT");          // Returns "DEFAULT"
- */
-export const chain_ = (val) => {
-  /** @private */
-  const inner = (v) => chain_(v);
 
-  return Object.freeze({
     /**
+     * Passes the internal value through a transformation function.
+     * Updates the internal state and returns the same Pipe instance.
      * @method modify
-     * @memberof module:modify-js.ChainBox
-     * @param {ModifyCallback} fn - Transformation function.
-     * @returns {ChainBox}
+     * @param {ModifyCallback} fn - The transformation function to execute.
+     * @returns {this} The current Pipe instance for further chaining.
      */
-    modify: (fn) => inner(fn(val)),
+    modify(fn) {
+        this.#value = fn(this.#value);
+        return this;
+    }
 
     /**
-     * @method _p
-     * @memberof module:modify-js.ChainBox
-     * @param {ModifyCallback} fn - Transformation function.
-     * @returns {ChainBox}
+     * Alias for {@link modify}.
+     * @param {ModifyCallback} fn
+     * @returns {this}
      */
-    _p: (fn) => inner(fn(val)),
+    _p(fn) { return this.modify(fn); }
 
     /**
-     * @method $p
-     * @memberof module:modify-js.ChainBox
-     * @param {ModifyCallback} fn - Transformation function.
-     * @returns {ChainBox}
+     * Alias for {@link modify}.
+     * @param {ModifyCallback} fn
+     * @returns {this}
      */
-    $p: (fn) => inner(fn(val)),
+    $p(fn) { return this.modify(fn); }
+
 
     /**
+     * Extracts the value from the pipe and terminates the chain.
+     * If the internal value is null or undefined, the provided default is returned.
      * @method out
-     * @memberof module:modify-js.ChainBox
-     * @param {any} [def] - Optional fallback value if the result is null/undefined.
-     * @returns {any}
+     * @param {any} [def] - Optional fallback value if the pipe's value is null/undefined.
+     * @param {boolean} [lock=true] - If true, wipes the internal state and freezes the object.
+     * @returns {any} The final transformed value or the default fallback.
      */
-    out: (def) => (val == null ? def : val)
-  });
-};
-
-/**
- * A shorthand method for chain_ function.
- * @function chain$
- * @returns {ChainBox} A chainable object containing transformation methods.
- */
-export const chain$ = (() => chain_)();
-
-
-/**
- * The transformation callback passed to .modify() or shorthands.
- * @callback ModifyCallback
- * @param {any} instance - The object instance the method was called upon.
- * @returns {any} - The result of the transformation.
- */
-
-/**
- * Property descriptor for the utility methods.
- * @type {PropertyDescriptor}
- * @private
- */
-const modifyDefinition = Object.freeze({
-  // This prevents the new methods from breaking other libraries that loop over objects.
-  enumerable: false,  
-
-  // Allows the property to be deleted or changed later. 
-  configurable: true,  
-
-  // Allows the value (the function itself) to be changed using an assignment operator (=).
-  writable: true,
-
-  /**
-   * @param {ModifyCallback} fn - The transformation function.
-   * @throws {TypeError} If fn is not a function.
-   * @returns {any} The result of fn(this).
-   */
-  value: (function () {
-    return function(fn) {
-      if (typeof fn !== 'function') throw new TypeError('Expected a function');
-      // Once the user uses .modify() or shorthands, they get a chain_ back.
-      // This may "solve" the friction of mid-chain null values.
-      return chain_(fn(this));
+    out(def, lock = true) {
+        try {
+            return this.#value == null
+                ? def
+                : this.#value;
+
+        } finally {
+            if (lock) {
+                this.#value = null;
+                Object.freeze(this);
+            }
+        }
     }
-  })()
-});
-
 
-/**
- * Removes .modify() and shorthand pipeline methods from all patched constructors.
- * This restores the environment to its original state by deleting the injected
- * prototype properties.
- * @function ejectModify
- * @memberof module:modify-js
- * @param {ModifyOptions} [options={}] - Configuration for the ejection process.
- * @param {boolean} [options.verbose=true] - If true, logs restoration status and warnings.
- * @returns {void}
- * @example
- * ejectModify({ verbose: false }); // Clean up the prototypes
- */
-export function ejectModify({ verbose = true } = {}) {
-  /** @type {Array<Function>} */
-  const targets = getAppliedTargets();
+    /**
+     * Alias for {@link out}.
+     * @param {any} [def]
+     * @param {boolean} [lock=true]
+     * @returns {any}
+     */
+    _o(def, lock) { return this.out(def, lock); }
 
-  targets.forEach(target => {
-    try {
-      const proto = target.prototype;
+    /**
+     * Alias for {@link out}.
+     * @param {any} [def]
+     * @param {boolean} [lock=true]
+     * @returns {any}
+     */
+    $o(def, lock) { return this.out(def, lock); }
 
-      // Remove the methods from the prototype chain
-      // These correspond to the methods defined in applyModify
-      delete proto.modify;
-      delete proto._p;
-      delete proto.$p;
 
-      // Remove specifically this target from the tracking Set
-      appliedTargets.delete(target);
-    } 
+    /**
+     * Checks if the pipe instance has been locked and frozen.
+     * A locked pipe can no longer be modified or used to extract values.
+     * @method isLocked
+     * @returns {boolean} True if the instance is frozen, false otherwise.
+     */
+    isLocked() { return Object.isFrozen(this); }
 
-    catch (e) {
-      if (verbose)
-        console.warn(
-          `[modify-js] Skipping ${target.name || 'Anonymous'}: ` +
-          `Unable to eject. Reason: ${e.message}`
-        );
-    }
-  });
+    /** Alias for {@link isLocked} */
+    _l() { return this.isLocked(); }
 
-  // Final reset of global internal state
-  if (appliedTargets.size <= 0) {
-    if (verbose)
-      console.log("[modify-js] Environment fully restored.");
-    isApplied = false;
-  }
+    /** Alias for {@link isLocked} */
+    $l() { return this.isLocked(); }
 }
 
-
 /**
- * Injects .modify() and shorthands into specified prototype chains.
- * Follows the Principle of Least Power; it does not patch globally 
- * unless explicitly passed the results of {@link module:modify-js.discover}.
- * These methods return a {@link ChainBox} to ensure subsequent calls are null-safe.
- * 
- * @function applyModify
- * @example
- * // Manual explicit injection
- * applyModify([Array, String, Boolean]);
- * 
- * @example
- * // Intentional global injection
- * applyModify(discover(), __F0V0);
- * 
+ * Entry point to create a new Pipe instance.
+ * @function chain_
+ * @param {any} val - The value to start the pipeline with.
+ * @returns {Pipe} A new Pipe container.
  * @example
- * // Usage in code
- * "hello"._p(s => s.toUpperCase()).modify(s => s + "!!!").out(); // "HELLO!!!"
- * 
- * @param {Array<Function>} [targets=[]] - An array of constructors to patch.
- * @param {ModifyOptions} [options={}] - Configuration for injection behavior.
- * @returns {void}
+ * const result = chain_(" hello ")
+ *     ._p(s => s.trim())
+ *     ._p(s => s.toUpperCase())
+ *     .out(); // "HELLO"
  */
-export function applyModify(targets = [], { force = false, verbose = true } = {}) {
-  // Exit early if no work is requested and library was already used
-  if (isApplied && !force && targets.length <= 0) return;
-
-  if (!Array.isArray(targets))
-    throw new Error('applyModify requires an array of constructors. Use discover() to get all available.');
-
-  targets.forEach(target => {
-    // Idempotency check
-    if (appliedTargets.has(target) && !force) return;
-
-    const proto = target?.prototype;
-
-    // Validate target has a prototype to extend
-    if (!proto) {
-      if (verbose) console.warn(`[modify-js] Skipping ${target}: No prototype available.`);
-      return;
-    }
-
-    const methods = ['modify', '_p', '$p'];
+export const chain_ = (val) => new Pipe(val);
 
-    methods.forEach(methodName => {
-      const exists = Object.prototype.hasOwnProperty.call(proto, methodName);
-
-      if (!exists || force) {
-        try {
-          Object.defineProperty(proto, methodName, modifyDefinition);
-        }
-        catch (e) {
-          if (verbose)
-            console.warn(
-              `[modify-js] Skipping ${target.name || 'Anonymous'}: ` +
-              `Unable to inject .${methodName}(). Reason: ${e.message}`
-            );
-        }
-
-      } else if (verbose) {
-        console.warn(`[modify-js] Skipping ${target.name || 'Anonymous'}: .${methodName}() already exists.`);
-      }
-    });
-
-    appliedTargets.add(target);
-  });
-
-  isApplied = true;
-}
+/**
+ * Shorthand alias for {@link chain_}.
+ * @function chain$
+ * @param {any} val
+ * @returns {Pipe}
+ */
+export const chain$ = (val) => new Pipe(val);
 
-export default applyModify;
+export default chain_;