First commit

2026-01-12 13:12:46 +01:00
parent b2d9501f6d
commit a1fbd8acf5
4413 changed files with 1245183 additions and 0 deletions
--- a/node_modules/@pinojs/redact/README.md
+++ b/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.