@farthershore/cli 0.3.9 → 0.3.10

package/node_modules/@pinojs/redact/README.md

@@ -0,0 +1,350 @@
+# @pinojs/redact
+
+> Smart object redaction for JavaScript applications - safe AND fast!
+
+Redact JS objects with the same API as [fast-redact](https://github.com/davidmarkclements/fast-redact), but uses innovative **selective cloning** instead of mutating the original. This provides immutability guarantees with **performance competitive** to fast-redact for real-world usage patterns.
+
+## Install
+
+```bash
+npm install @pinojs/redact
+```
+
+## Usage
+
+```js
+const slowRedact = require('@pinojs/redact')
+
+const redact = slowRedact({
+  paths: ['headers.cookie', 'headers.authorization', 'user.password']
+})
+
+const obj = {
+  headers: {
+    cookie: 'secret-session-token',
+    authorization: 'Bearer abc123',
+    'x-forwarded-for': '192.168.1.1'
+  },
+  user: {
+    name: 'john',
+    password: 'secret123'
+  }
+}
+
+console.log(redact(obj))
+// Output: {"headers":{"cookie":"[REDACTED]","authorization":"[REDACTED]","x-forwarded-for":"192.168.1.1"},"user":{"name":"john","password":"[REDACTED]"}}
+
+// Original object is completely unchanged:
+console.log(obj.headers.cookie) // 'secret-session-token'
+```
+
+## API
+
+### slowRedact(options) → Function
+
+Creates a redaction function with the specified options.
+
+#### Options
+
+- **paths** `string[]` (required): An array of strings describing the nested location of a key in an object
+- **censor** `any` (optional, default: `'[REDACTED]'`): The value to replace sensitive data with. Can be a static value or function.
+- **serialize** `Function|boolean` (optional, default: `JSON.stringify`): Serialization function. Set to `false` to return the redacted object.
+- **remove** `boolean` (optional, default: `false`): Remove redacted keys from serialized output
+- **strict** `boolean` (optional, default: `true`): Throw on non-object values or pass through primitives
+
+#### Path Syntax
+
+Supports the same path syntax as fast-redact:
+
+- **Dot notation**: `'user.name'`, `'headers.cookie'`
+- **Bracket notation**: `'user["password"]'`, `'headers["X-Forwarded-For"]'`
+- **Array indices**: `'users[0].password'`, `'items[1].secret'`
+- **Wildcards**:
+  - Terminal: `'users.*.password'` (redacts password for all users)
+  - Intermediate: `'*.password'` (redacts password at any level)
+  - Array wildcard: `'items.*'` (redacts all array elements)
+
+#### Examples
+
+**Custom censor value:**
+```js
+const redact = slowRedact({
+  paths: ['password'],
+  censor: '***HIDDEN***'
+})
+```
+
+**Dynamic censor function:**
+```js
+const redact = slowRedact({
+  paths: ['password'],
+  censor: (value, path) => `REDACTED:${path}`
+})
+```
+
+**Return object instead of JSON string:**
+```js
+const redact = slowRedact({
+  paths: ['secret'],
+  serialize: false
+})
+
+const result = redact({ secret: 'hidden', public: 'data' })
+console.log(result.secret) // '[REDACTED]'
+console.log(result.public) // 'data'
+
+// Restore original values
+const restored = result.restore()
+console.log(restored.secret) // 'hidden'
+```
+
+**Custom serialization:**
+```js
+const redact = slowRedact({
+  paths: ['password'],
+  serialize: obj => JSON.stringify(obj, null, 2)
+})
+```
+
+**Remove keys instead of redacting:**
+```js
+const redact = slowRedact({
+  paths: ['password', 'user.secret'],
+  remove: true
+})
+
+const obj = { username: 'john', password: 'secret123', user: { name: 'Jane', secret: 'hidden' } }
+console.log(redact(obj))
+// Output: {"username":"john","user":{"name":"Jane"}}
+// Note: 'password' and 'user.secret' are completely absent, not redacted
+```
+
+**Wildcard patterns:**
+```js
+// Redact all properties in secrets object
+const redact1 = slowRedact({ paths: ['secrets.*'] })
+
+// Redact password for any user
+const redact2 = slowRedact({ paths: ['users.*.password'] })
+
+// Redact all items in an array
+const redact3 = slowRedact({ paths: ['items.*'] })
+
+// Remove all secrets instead of redacting them
+const redact4 = slowRedact({ paths: ['secrets.*'], remove: true })
+```
+
+## Key Differences from fast-redact
+
+### Safety First
+- **No mutation**: Original objects are never modified
+- **Selective cloning**: Only clones paths that need redaction, shares references for everything else
+- **Restore capability**: Can restore original values when `serialize: false`
+
+### Feature Compatibility
+- **Remove option**: Full compatibility with fast-redact's `remove: true` option to completely omit keys from output
+- **All path patterns**: Supports same syntax including wildcards, bracket notation, and array indices
+- **Censor functions**: Dynamic censoring with path information passed as arrays
+- **Serialization**: Custom serializers and `serialize: false` mode
+
+### Smart Performance Approach
+- **Selective cloning**: Analyzes redaction paths and only clones necessary object branches
+- **Reference sharing**: Non-redacted properties maintain original object references
+- **Memory efficiency**: Dramatically reduced memory usage for large objects with minimal redaction
+- **Setup-time optimization**: Path analysis happens once during setup, not per redaction
+
+### When to Use @pinojs/redact
+- When immutability is critical
+- When you need to preserve original objects
+- When objects are shared across multiple contexts
+- In functional programming environments
+- When debugging and you need to compare before/after
+- **Large objects with selective redaction** (now performance-competitive!)
+- When memory efficiency with reference sharing is important
+
+### When to Use fast-redact
+- When absolute maximum performance is critical
+- In extremely high-throughput scenarios (>100,000 ops/sec)
+- When you control the object lifecycle and mutation is acceptable
+- Very small objects where setup overhead matters
+
+## Performance Benchmarks
+
+@pinojs/redact uses **selective cloning** that provides good performance while maintaining immutability guarantees:
+
+### Performance Results
+
+| Operation Type | @pinojs/redact | fast-redact | Performance Ratio |
+|---------------|-------------|-------------|-------------------|
+| **Small objects** | ~690ns | ~200ns | ~3.5x slower |
+| **Large objects (minimal redaction)** | **~18μs** | ~17μs | **~same performance** |
+| **Large objects (wildcards)** | **~48μs** | ~37μs | **~1.3x slower** |
+| **No redaction (large objects)** | **~18μs** | ~17μs | **~same performance** |
+
+### Performance Improvements
+
+@pinojs/redact is performance-competitive with fast-redact for large objects.
+
+1. **Selective cloning approach**: Only clones object paths that need redaction
+2. **Reference sharing**: Non-redacted properties share original object references
+3. **Setup-time optimization**: Path analysis happens once, not per redaction
+4. **Memory efficiency**: Dramatically reduced memory usage for typical use cases
+
+### Benchmark Details
+
+**Small Objects (~180 bytes)**:
+- @pinojs/redact: **690ns** per operation
+- fast-redact: **200ns** per operation
+- **Slight setup overhead for small objects**
+
+**Large Objects (~18KB, minimal redaction)**:
+- @pinojs/redact: **18μs** per operation
+- fast-redact: **17μs** per operation
+- Near-identical performance
+
+**Large Objects (~18KB, wildcard patterns)**:
+- @pinojs/redact: **48μs** per operation
+- fast-redact: **37μs** per operation
+- Competitive performance for complex patterns
+
+**Memory Considerations**:
+- @pinojs/redact: **Selective reference sharing** (much lower memory usage than before)
+- fast-redact: Mutates in-place (lowest memory usage)
+- Large objects with few redacted paths now share most references
+
+### When Performance Matters
+
+Choose **fast-redact** when:
+- Absolute maximum performance is critical (>100,000 ops/sec)
+- Working with very small objects frequently
+- Mutation is acceptable and controlled
+- Every microsecond counts
+
+Choose **@pinojs/redact** when:
+- Immutability is required (with competitive performance)
+- Objects are shared across contexts
+- Large objects with selective redaction
+- Memory efficiency through reference sharing is important
+- Safety and functionality are priorities
+- Most production applications (performance gap is minimal)
+
+Run benchmarks yourself:
+```bash
+npm run bench
+```
+
+## How Selective Cloning Works
+
+@pinojs/redact uses an innovative **selective cloning** approach that provides immutability guarantees while dramatically improving performance:
+
+### Traditional Approach (before optimization)
+```js
+// Old approach: Deep clone entire object, then redact
+const fullClone = deepClone(originalObject)  // Clone everything
+redact(fullClone, paths)                     // Then redact specific paths
+```
+
+### Selective Cloning Approach (current)
+```js
+// New approach: Analyze paths, clone only what's needed
+const pathStructure = buildPathStructure(paths)  // One-time setup
+const selectiveClone = cloneOnlyNeededPaths(obj, pathStructure)  // Smart cloning
+redact(selectiveClone, paths)  // Redact pre-identified paths
+```
+
+### Key Innovations
+
+1. **Path Analysis**: Pre-processes redaction paths into an efficient tree structure
+2. **Selective Cloning**: Only creates new objects for branches that contain redaction targets
+3. **Reference Sharing**: Non-redacted properties maintain exact same object references
+4. **Setup Optimization**: Path parsing happens once during redactor creation, not per redaction
+
+### Example: Reference Sharing in Action
+
+```js
+const largeConfig = {
+  database: { /* large config object */ },
+  api: { /* another large config */ },
+  secrets: { password: 'hidden', apiKey: 'secret' }
+}
+
+const redact = slowRedact({ paths: ['secrets.password'] })
+const result = redact(largeConfig)
+
+// Only secrets object is cloned, database and api share original references
+console.log(result.database === largeConfig.database)  // true - shared reference!
+console.log(result.api === largeConfig.api)            // true - shared reference!
+console.log(result.secrets === largeConfig.secrets)    // false - cloned for redaction
+```
+
+This approach provides **immutability where it matters** while **sharing references where it's safe**.
+
+## Remove Option
+
+The `remove: true` option provides full compatibility with fast-redact's key removal functionality:
+
+```js
+const redact = slowRedact({
+  paths: ['password', 'secrets.*', 'users.*.credentials'],
+  remove: true
+})
+
+const data = {
+  username: 'john',
+  password: 'secret123',
+  secrets: { apiKey: 'abc', token: 'xyz' },
+  users: [
+    { name: 'Alice', credentials: { password: 'pass1' } },
+    { name: 'Bob', credentials: { password: 'pass2' } }
+  ]
+}
+
+console.log(redact(data))
+// Output: {"username":"john","secrets":{},"users":[{"name":"Alice"},{"name":"Bob"}]}
+```
+
+### Remove vs Redact Behavior
+
+| Option | Behavior | Output Example |
+|--------|----------|----------------|
+| Default (redact) | Replaces values with censor | `{"password":"[REDACTED]"}` |
+| `remove: true` | Completely omits keys | `{}` |
+
+### Compatibility Notes
+
+- **Same output as fast-redact**: Identical JSON output when using `remove: true`
+- **Wildcard support**: Works with all wildcard patterns (`*`, `users.*`, `items.*.secret`)
+- **Array handling**: Array items are set to `undefined` (omitted in JSON output)
+- **Nested paths**: Supports deep removal (`users.*.credentials.password`)
+- **Serialize compatibility**: Only works with `JSON.stringify` serializer (like fast-redact)
+
+## Testing
+
+```bash
+# Run unit tests
+npm test
+
+# Run integration tests comparing with fast-redact
+npm run test:integration
+
+# Run all tests (unit + integration)
+npm run test:all
+
+# Run benchmarks
+npm run bench
+```
+
+### Test Coverage
+
+- **16 unit tests**: Core functionality and edge cases
+- **16 integration tests**: Output compatibility with fast-redact
+- **All major features**: Paths, wildcards, serialization, custom censors
+- **Performance benchmarks**: Direct comparison with fast-redact
+
+## License
+
+MIT
+
+## Contributing
+
+Pull requests welcome! Please ensure all tests pass and add tests for new features.

package/node_modules/@pinojs/redact/benchmarks/basic.js

@@ -0,0 +1,184 @@
+const { bench, group, run } = require('mitata')
+const slowRedact = require('../index.js')
+const fastRedact = require('fast-redact')
+
+// Test objects
+const smallObj = {
+  user: { name: 'john', password: 'secret123' },
+  headers: { cookie: 'session-token', authorization: 'Bearer abc123' }
+}
+
+const largeObj = {
+  users: [],
+  metadata: {
+    version: '1.0.0',
+    secret: 'app-secret-key',
+    database: {
+      host: 'localhost',
+      password: 'db-password'
+    }
+  }
+}
+
+// Populate users array with for loop instead of Array.from
+for (let i = 0; i < 100; i++) {
+  largeObj.users.push({
+    id: i,
+    name: `user${i}`,
+    email: `user${i}@example.com`,
+    password: `secret${i}`,
+    profile: {
+      age: 20 + (i % 50),
+      preferences: {
+        theme: 'dark',
+        notifications: true,
+        apiKey: `key-${i}-secret`
+      }
+    }
+  })
+}
+
+// Redaction configurations
+const basicSlowRedact = slowRedact({
+  paths: ['user.password', 'headers.cookie']
+})
+
+const basicFastRedact = fastRedact({
+  paths: ['user.password', 'headers.cookie']
+})
+
+const wildcardSlowRedact = slowRedact({
+  paths: ['users.*.password', 'users.*.profile.preferences.apiKey']
+})
+
+const wildcardFastRedact = fastRedact({
+  paths: ['users.*.password', 'users.*.profile.preferences.apiKey']
+})
+
+const deepSlowRedact = slowRedact({
+  paths: ['metadata.secret', 'metadata.database.password']
+})
+
+const deepFastRedact = fastRedact({
+  paths: ['metadata.secret', 'metadata.database.password']
+})
+
+group('Small Object Redaction - @pinojs/redact', () => {
+  bench('basic paths', () => {
+    basicSlowRedact(smallObj)
+  })
+
+  bench('serialize: false', () => {
+    const redact = slowRedact({
+      paths: ['user.password'],
+      serialize: false
+    })
+    redact(smallObj)
+  })
+
+  bench('custom censor function', () => {
+    const redact = slowRedact({
+      paths: ['user.password'],
+      censor: (value, path) => `HIDDEN:${path}`
+    })
+    redact(smallObj)
+  })
+})
+
+group('Small Object Redaction - fast-redact', () => {
+  bench('basic paths', () => {
+    basicFastRedact(smallObj)
+  })
+
+  bench('serialize: false', () => {
+    const redact = fastRedact({
+      paths: ['user.password'],
+      serialize: false
+    })
+    redact(smallObj)
+  })
+
+  bench('custom censor function', () => {
+    const redact = fastRedact({
+      paths: ['user.password'],
+      censor: (value, path) => `HIDDEN:${path}`
+    })
+    redact(smallObj)
+  })
+})
+
+group('Large Object Redaction - @pinojs/redact', () => {
+  bench('wildcard patterns', () => {
+    wildcardSlowRedact(largeObj)
+  })
+
+  bench('deep nested paths', () => {
+    deepSlowRedact(largeObj)
+  })
+
+  bench('multiple wildcards', () => {
+    const redact = slowRedact({
+      paths: ['users.*.password', 'users.*.profile.preferences.*']
+    })
+    redact(largeObj)
+  })
+})
+
+group('Large Object Redaction - fast-redact', () => {
+  bench('wildcard patterns', () => {
+    wildcardFastRedact(largeObj)
+  })
+
+  bench('deep nested paths', () => {
+    deepFastRedact(largeObj)
+  })
+
+  bench('multiple wildcards', () => {
+    const redact = fastRedact({
+      paths: ['users.*.password', 'users.*.profile.preferences.*']
+    })
+    redact(largeObj)
+  })
+})
+
+group('Direct Performance Comparison', () => {
+  bench('@pinojs/redact - basic paths', () => {
+    basicSlowRedact(smallObj)
+  })
+
+  bench('fast-redact - basic paths', () => {
+    basicFastRedact(smallObj)
+  })
+
+  bench('@pinojs/redact - wildcards', () => {
+    wildcardSlowRedact(largeObj)
+  })
+
+  bench('fast-redact - wildcards', () => {
+    wildcardFastRedact(largeObj)
+  })
+})
+
+group('Object Cloning Overhead', () => {
+  bench('@pinojs/redact - no redaction (clone only)', () => {
+    const redact = slowRedact({ paths: [] })
+    redact(smallObj)
+  })
+
+  bench('fast-redact - no redaction', () => {
+    const redact = fastRedact({ paths: [] })
+    redact(smallObj)
+  })
+
+  bench('@pinojs/redact - large object clone', () => {
+    const redact = slowRedact({ paths: [] })
+    redact(largeObj)
+  })
+
+  bench('fast-redact - large object', () => {
+    const redact = fastRedact({ paths: [] })
+    redact(largeObj)
+  })
+})
+
+run()

package/node_modules/@pinojs/redact/eslint.config.js

@@ -0,0 +1 @@
+module.exports = require('neostandard')()

package/node_modules/@pinojs/redact/index.d.ts

@@ -0,0 +1,52 @@
+export = F;
+
+/**
+ * When called without any options, or with a zero length paths array, @pinojs/redact will return JSON.stringify or the serialize option, if set.
+ * @param redactOptions
+ * @param redactOptions.paths An array of strings describing the nested location of a key in an object.
+ * @param redactOptions.censor This is the value which overwrites redacted properties.
+ * @param redactOptions.remove The remove option, when set to true will cause keys to be removed from the serialized output.
+ * @param redactOptions.serialize The serialize option may either be a function or a boolean. If a function is supplied, this will be used to serialize the redacted object.
+ * @param redactOptions.strict The strict option, when set to true, will cause the redactor function to throw if instead of an object it finds a primitive.
+ * @returns Redacted value from input
+ */
+declare function F(
+  redactOptions: F.RedactOptionsNoSerialize
+): F.redactFnNoSerialize;
+declare function F(redactOptions?: F.RedactOptions): F.redactFn;
+
+declare namespace F {
+  /** Redacts input */
+  type redactFn = <T>(input: T) => string | T;
+
+  /** Redacts input without serialization */
+  type redactFnNoSerialize = redactFn & {
+    /** Method that allowing the redacted keys to be restored with the original data. Supplied only when serialize option set to false. */
+    restore<T>(input: T): T;
+  };
+
+  interface RedactOptions {
+    /** An array of strings describing the nested location of a key in an object. */
+    paths?: string[] | undefined;
+
+    /** This is the value which overwrites redacted properties. */
+    censor?: string | ((v: any) => any) | undefined;
+
+    /** The remove option, when set to true will cause keys to be removed from the serialized output. */
+    remove?: boolean | undefined;
+
+    /**
+     * The serialize option may either be a function or a boolean. If a function is supplied, this will be used to serialize the redacted object.
+     * The default serialize is the function JSON.stringify
+     */
+    serialize?: boolean | ((v: any) => any) | undefined;
+
+    /** The strict option, when set to true, will cause the redactor function to throw if instead of an object it finds a primitive. */
+    strict?: boolean | undefined;
+  }
+
+  /** RedactOptions without serialization. Instead of the serialized object, the output of the redactor function will be the mutated object itself. */
+  interface RedactOptionsNoSerialize extends RedactOptions {
+    serialize: false;
+  }
+}