@heroku/js-blanket 0.0.0 → 0.0.1

package/src/core/types.test.ts

@@ -1,516 +0,0 @@
-/**
- * Type Safety Tests for Core Scrubber
- *
- * These tests validate that TypeScript types are preserved correctly through scrubbing operations.
- * They use compile-time type assertions to ensure type safety without runtime overhead.
- *
- * Run with: pnpm test (type-checked during pretest)
- */
-
-import { expect } from 'chai';
-import { Scrubber } from './scrubber.js';
-import type { ScrubConfig, ScrubResult } from './types.js';
-
-/**
- * Compile-time type assertion helper
- * If T is not assignable to Expected, TypeScript will error at compile time
- */
-type AssertType<T, Expected> = T extends Expected
-  ? Expected extends T
-    ? true
-    : never
-  : never;
-
-describe('Type Safety', () => {
-  describe('Generic Type Preservation', () => {
-    it('preserves simple object types', () => {
-      interface User {
-        name: string;
-        email: string;
-        password: string;
-      }
-
-      const scrubber = new Scrubber({ fields: ['password'] });
-      const user: User = {
-        name: 'John',
-        email: 'john@example.com',
-        password: 'secret',
-      };
-
-      const result = scrubber.scrub(user);
-
-      // Compile-time assertion: result.data should be User type
-      const typeCheck: AssertType<typeof result.data, User> = true;
-      expect(typeCheck).to.be.true;
-
-      // Runtime validation
-      expect(result.data).to.have.property('name');
-      expect(result.data).to.have.property('email');
-      expect(result.data).to.have.property('password');
-    });
-
-    it('preserves nested object types', () => {
-      interface Address {
-        street: string;
-        city: string;
-        zip: string;
-      }
-
-      interface UserProfile {
-        user: {
-          name: string;
-          email: string;
-        };
-        address: Address;
-        metadata: {
-          lastLogin: string;
-          loginCount: number;
-        };
-      }
-
-      const scrubber = new Scrubber({ fields: ['email'] });
-      const profile: UserProfile = {
-        user: { name: 'John', email: 'john@example.com' },
-        address: { street: '123 Main St', city: 'Springfield', zip: '12345' },
-        metadata: { lastLogin: '2024-01-01', loginCount: 42 },
-      };
-
-      const _result = scrubber.scrub(profile);
-
-      // Compile-time assertion
-      const typeCheck: AssertType<typeof _result.data, UserProfile> = true;
-      expect(typeCheck).to.be.true;
-    });
-
-    it('preserves array types', () => {
-      interface Item {
-        id: number;
-        name: string;
-        secret: string;
-      }
-
-      const scrubber = new Scrubber({ fields: ['secret'] });
-      const items: Item[] = [
-        { id: 1, name: 'Item 1', secret: 'secret1' },
-        { id: 2, name: 'Item 2', secret: 'secret2' },
-      ];
-
-      const result = scrubber.scrub(items);
-
-      // Compile-time assertion
-      const typeCheck: AssertType<typeof result.data, Item[]> = true;
-      expect(typeCheck).to.be.true;
-
-      // Runtime validation
-      expect(result.data).to.be.an('array');
-      expect(result.data).to.have.lengthOf(2);
-    });
-
-    it('preserves union types', () => {
-      type ComplexUnion =
-        | { type: 'user'; name: string; email: string }
-        | { type: 'admin'; name: string; permissions: string[] };
-
-      const scrubber = new Scrubber({ fields: ['email'] });
-      const data: ComplexUnion = {
-        type: 'user',
-        name: 'John',
-        email: 'john@example.com',
-      };
-
-      const _result = scrubber.scrub(data);
-
-      // Compile-time assertion
-      const typeCheck: AssertType<typeof _result.data, ComplexUnion> = true;
-      expect(typeCheck).to.be.true;
-    });
-
-    it('preserves readonly types', () => {
-      interface ReadonlyUser {
-        readonly id: number;
-        readonly name: string;
-        password: string;
-      }
-
-      const scrubber = new Scrubber({ fields: ['password'] });
-      const user: ReadonlyUser = {
-        id: 1,
-        name: 'John',
-        password: 'secret',
-      };
-
-      const result = scrubber.scrub(user);
-
-      // Compile-time assertion
-      const typeCheck: AssertType<typeof result.data, ReadonlyUser> = true;
-      expect(typeCheck).to.be.true;
-
-      // Immutability: original should not be modified
-      expect(user.password).to.equal('secret');
-      expect(result.data.password).to.equal('[SCRUBBED]');
-    });
-
-    it('preserves optional property types', () => {
-      interface PartialUser {
-        name: string;
-        email?: string;
-        phone?: string;
-        password: string;
-      }
-
-      const scrubber = new Scrubber({ fields: ['password'] });
-      const user: PartialUser = {
-        name: 'John',
-        email: 'john@example.com',
-        // phone is omitted
-        password: 'secret',
-      };
-
-      const _result = scrubber.scrub(user);
-
-      // Compile-time assertion
-      const typeCheck: AssertType<typeof _result.data, PartialUser> = true;
-      expect(typeCheck).to.be.true;
-    });
-  });
-
-  describe('ScrubResult Type', () => {
-    it('has correct result structure', () => {
-      const scrubber = new Scrubber({ fields: ['password'] });
-      const data = { user: 'john', password: 'secret' };
-      const result = scrubber.scrub(data);
-
-      // Type assertion: result should be ScrubResult
-      const typeCheck: AssertType<
-        typeof result,
-        ScrubResult<typeof data>
-      > = true;
-      expect(typeCheck).to.be.true;
-
-      // Runtime validation
-      expect(result).to.have.property('data');
-      expect(result).to.have.property('scrubbed');
-      expect(result).to.have.property('scrubbedPaths');
-      expect(result.scrubbed).to.be.a('boolean');
-      expect(result.scrubbedPaths).to.be.an('array');
-    });
-
-    it('preserves input type in result.data', () => {
-      interface Input {
-        a: string;
-        b: number;
-        c: boolean;
-      }
-
-      const scrubber = new Scrubber({ fields: ['a'] });
-      const input: Input = { a: 'test', b: 42, c: true };
-      const _result: ScrubResult<Input> = scrubber.scrub(input);
-
-      // Compile-time assertion
-      const typeCheck: AssertType<typeof _result.data, Input> = true;
-      expect(typeCheck).to.be.true;
-    });
-  });
-
-  describe('ScrubConfig Type', () => {
-    it('accepts valid configurations', () => {
-      const config1: ScrubConfig = {
-        fields: ['password', 'apiToken'],
-      };
-
-      const config2: ScrubConfig = {
-        fields: ['password', /api[-_]?key/i],
-        paths: ['user.email'],
-        patterns: [/\d{3}-\d{2}-\d{4}/g],
-        replacement: '[REDACTED]',
-      };
-
-      const config3: ScrubConfig = {
-        fields: [],
-        paths: [],
-        patterns: [],
-        recursive: false,
-      };
-
-      // All should be valid ScrubConfig types
-      expect(config1).to.be.an('object');
-      expect(config2).to.be.an('object');
-      expect(config3).to.be.an('object');
-    });
-
-    it('allows partial configurations', () => {
-      const partial1: ScrubConfig = {};
-      const partial2: ScrubConfig = { fields: ['password'] };
-      const partial3: ScrubConfig = { replacement: '[X]' };
-
-      expect(partial1).to.be.an('object');
-      expect(partial2).to.be.an('object');
-      expect(partial3).to.be.an('object');
-    });
-  });
-
-  describe('Complex Type Scenarios', () => {
-    it('handles deeply nested generic types', () => {
-      interface DeepNested<T> {
-        level1: {
-          level2: {
-            level3: {
-              level4: {
-                value: T;
-                secret: string;
-              };
-            };
-          };
-        };
-      }
-
-      const scrubber = new Scrubber({ fields: ['secret'] });
-      const data: DeepNested<number> = {
-        level1: {
-          level2: {
-            level3: {
-              level4: {
-                value: 42,
-                secret: 'hidden',
-              },
-            },
-          },
-        },
-      };
-
-      const _result = scrubber.scrub(data);
-
-      // Compile-time assertion
-      const typeCheck: AssertType<
-        typeof _result.data,
-        DeepNested<number>
-      > = true;
-      expect(typeCheck).to.be.true;
-    });
-
-    it('handles arrays of complex types', () => {
-      interface Event {
-        id: string;
-        timestamp: Date;
-        user: {
-          id: string;
-          email: string;
-        };
-        metadata: Record<string, unknown>;
-      }
-
-      const scrubber = new Scrubber({ fields: ['email'] });
-      const events: Event[] = [
-        {
-          id: '1',
-          timestamp: new Date(),
-          user: { id: 'u1', email: 'user1@example.com' },
-          metadata: { key: 'value' },
-        },
-        {
-          id: '2',
-          timestamp: new Date(),
-          user: { id: 'u2', email: 'user2@example.com' },
-          metadata: { key: 'value' },
-        },
-      ];
-
-      const _result = scrubber.scrub(events);
-
-      // Compile-time assertion
-      const typeCheck: AssertType<typeof _result.data, Event[]> = true;
-      expect(typeCheck).to.be.true;
-    });
-
-    it('handles Record types', () => {
-      type UserMap = Record<string, { name: string; password: string }>;
-
-      const scrubber = new Scrubber({ fields: ['password'] });
-      const users: UserMap = {
-        user1: { name: 'John', password: 'secret1' },
-        user2: { name: 'Jane', password: 'secret2' },
-      };
-
-      const _result = scrubber.scrub(users);
-
-      // Compile-time assertion
-      const typeCheck: AssertType<typeof _result.data, UserMap> = true;
-      expect(typeCheck).to.be.true;
-    });
-
-    it('handles mixed primitive and object types', () => {
-      interface MixedData {
-        string: string;
-        number: number;
-        boolean: boolean;
-        null: null;
-        undefined: undefined;
-        date: Date;
-        regex: RegExp;
-        object: { key: string };
-        array: number[];
-      }
-
-      const scrubber = new Scrubber({ fields: ['key'] });
-      const data: MixedData = {
-        string: 'text',
-        number: 42,
-        boolean: true,
-        null: null,
-        undefined: undefined,
-        date: new Date(),
-        regex: /test/,
-        object: { key: 'value' },
-        array: [1, 2, 3],
-      };
-
-      const _result = scrubber.scrub(data);
-
-      // Compile-time assertion
-      const typeCheck: AssertType<typeof _result.data, MixedData> = true;
-      expect(typeCheck).to.be.true;
-    });
-
-    it('handles tuple types', () => {
-      type UserTuple = [string, number, boolean, { password: string }];
-
-      const scrubber = new Scrubber({ fields: ['password'] });
-      const tuple: UserTuple = ['John', 30, true, { password: 'secret' }];
-
-      const result = scrubber.scrub(tuple);
-
-      // Note: TypeScript treats tuples as arrays at runtime, so the type is preserved
-      // but the specific tuple structure is maintained
-      expect(result.data).to.be.an('array');
-      expect(result.data).to.have.lengthOf(4);
-    });
-
-    it('preserves type safety with unknown types', () => {
-      const scrubber = new Scrubber({ fields: ['password'] });
-      const data: unknown = { user: 'john', password: 'secret' };
-
-      const _result = scrubber.scrub(data);
-
-      // Compile-time assertion: unknown in, unknown out
-      const typeCheck: AssertType<typeof _result.data, unknown> = true;
-      expect(typeCheck).to.be.true;
-    });
-  });
-
-  describe('Type Inference', () => {
-    it('infers types from literal objects', () => {
-      const scrubber = new Scrubber({ fields: ['password'] });
-
-      // Type should be inferred from the literal
-      const result = scrubber.scrub({
-        name: 'John',
-        email: 'john@example.com',
-        password: 'secret',
-      });
-
-      // TypeScript infers the exact shape
-      expect(result.data).to.have.property('name');
-      expect(result.data).to.have.property('email');
-      expect(result.data).to.have.property('password');
-    });
-
-    it('works with const assertions', () => {
-      const scrubber = new Scrubber({ fields: ['password'] });
-
-      const data = {
-        name: 'John',
-        role: 'admin',
-        password: 'secret',
-      } as const;
-
-      // Type should preserve readonly properties from const assertion
-      const result = scrubber.scrub(data);
-
-      expect(result.data.name).to.equal('John');
-      expect(result.data.role).to.equal('admin');
-    });
-  });
-
-  describe('Edge Case Types', () => {
-    it('handles empty objects', () => {
-      const scrubber = new Scrubber({ fields: ['password'] });
-      const empty = {};
-
-      const result = scrubber.scrub(empty);
-
-      const typeCheck: AssertType<typeof result.data, typeof empty> = true;
-      expect(typeCheck).to.be.true;
-      expect(result.data).to.deep.equal({});
-    });
-
-    it('handles primitives directly', () => {
-      const scrubber = new Scrubber({ fields: ['password'] });
-
-      const string = 'test';
-      const number = 42;
-      const boolean = true;
-      const nullVal = null;
-
-      expect(scrubber.scrub(string).data).to.equal(string);
-      expect(scrubber.scrub(number).data).to.equal(number);
-      expect(scrubber.scrub(boolean).data).to.equal(boolean);
-      expect(scrubber.scrub(nullVal).data).to.equal(nullVal);
-    });
-
-    it('handles circular references with type preservation', () => {
-      interface Circular {
-        name: string;
-        password: string;
-        self?: Circular;
-      }
-
-      const scrubber = new Scrubber({ fields: ['password'] });
-      const obj: Circular = {
-        name: 'test',
-        password: 'secret',
-      };
-      obj.self = obj; // Circular reference
-
-      const result = scrubber.scrub(obj);
-
-      // Type is preserved even with circular reference
-      const typeCheck: AssertType<typeof result.data, Circular> = true;
-      expect(typeCheck).to.be.true;
-      expect(result.data.name).to.equal('test');
-    });
-  });
-
-  describe('Strict TypeScript Compliance', () => {
-    it('respects noUncheckedIndexedAccess', () => {
-      const scrubber = new Scrubber({ fields: ['password'] });
-      const data: Record<string, string> = {
-        user: 'john',
-        password: 'secret',
-      };
-
-      const result = scrubber.scrub(data);
-
-      // With noUncheckedIndexedAccess, indexed access returns string | undefined
-      const value = result.data['nonexistent'];
-      expect(value).to.be.undefined;
-    });
-
-    it('respects strictNullChecks', () => {
-      interface NullableData {
-        value: string | null;
-        optional?: string;
-      }
-
-      const scrubber = new Scrubber({ fields: ['value'] });
-      const data: NullableData = {
-        value: null,
-      };
-
-      const _result = scrubber.scrub(data);
-
-      // Compile-time assertion
-      const typeCheck: AssertType<typeof _result.data, NullableData> = true;
-      expect(typeCheck).to.be.true;
-    });
-  });
-});

package/src/core/types.ts

@@ -1,176 +0,0 @@
-/**
- * Configuration for the Scrubber
- *
- * Defines how the scrubber should identify and replace sensitive data.
- * Supports three complementary scrubbing strategies:
- *
- * 1. **Field-based scrubbing** (`fields`): Matches field names at any depth in the object tree
- * 2. **Path-based scrubbing** (`paths`): Matches specific dot-notation paths
- * 3. **Pattern-based scrubbing** (`patterns`): Matches regex patterns in string content
- *
- * All three strategies can be used together for comprehensive data scrubbing.
- *
- * @example Field-based configuration
- * ```typescript
- * const config: ScrubConfig = {
- *   fields: ['password', 'apiToken', /api[-_]?key/i], // Strings and regex patterns
- *   replacement: '[REDACTED]'
- * };
- * ```
- *
- * @example Path-based configuration
- * ```typescript
- * const config: ScrubConfig = {
- *   paths: [
- *     'user.email',
- *     'request.headers.authorization',
- *     'items[0].password'  // Array index notation
- *   ]
- * };
- * ```
- *
- * @example Pattern-based configuration
- * ```typescript
- * const config: ScrubConfig = {
- *   patterns: [
- *     /\b\d{3}-\d{2}-\d{4}\b/g,           // SSN
- *     /\d{4}-\d{4}-\d{4}-\d{4}/g,        // Credit card
- *     /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}/g  // Email
- *   ]
- * };
- * ```
- */
-export interface ScrubConfig {
-  /**
-   * Field-based scrubbing: matches field names at any depth
-   *
-   * Supports both exact string matches and regular expressions for flexible matching.
-   * String matches are case-insensitive and use substring matching.
-   *
-   * @example
-   * ```typescript
-   * fields: [
-   *   'password',           // Matches 'password', 'Password', 'old_password', etc.
-   *   'apiToken',           // Matches 'apiToken', 'api_token', etc.
-   *   /api[-_]?key/i,       // Regex: matches 'api_key', 'api-key', 'apikey' (case insensitive)
-   *   /^secret$/            // Exact match: only 'secret', not 'my_secret'
-   * ]
-   * ```
-   */
-  fields?: (string | RegExp)[];
-
-  /**
-   * Path-based scrubbing: matches specific dot-notation paths
-   *
-   * Use dot notation to target specific fields in nested objects.
-   * Supports array index notation (e.g., `items[0].password`).
-   *
-   * @example
-   * ```typescript
-   * paths: [
-   *   'user.email',                        // Scrubs obj.user.email
-   *   'request.headers.authorization',     // Nested path
-   *   'items[0].secret',                   // Array index notation
-   *   'users[0]'                           // Scrubs entire array element
-   * ]
-   * ```
-   */
-  paths?: string[];
-
-  /**
-   * Pattern-based scrubbing: regex patterns for content scrubbing
-   *
-   * Scans string values and replaces content matching the patterns.
-   * Use the global flag (`/pattern/g`) to replace all matches in a string.
-   *
-   * **Note**: Patterns are applied to string values only, not to field names or paths.
-   *
-   * @example
-   * ```typescript
-   * patterns: [
-   *   /\b\d{3}-\d{2}-\d{4}\b/g,      // Social Security Number
-   *   /\d{4}-\d{4}-\d{4}-\d{4}/g,    // Credit Card
-   *   /Bearer\s+[A-Za-z0-9._-]+/g    // Bearer tokens
-   * ]
-   * ```
-   */
-  patterns?: RegExp[];
-
-  /**
-   * Replacement string for scrubbed values
-   *
-   * @default '[SCRUBBED]'
-   *
-   * @example
-   * ```typescript
-   * replacement: '[REDACTED]'     // Custom replacement text
-   * replacement: '***'            // Simple masking
-   * replacement: ''               // Empty string (removes content)
-   * ```
-   */
-  replacement?: string;
-
-  /**
-   * Whether to recursively scrub nested objects
-   *
-   * When `true`, the scrubber traverses the entire object tree.
-   * When `false`, only top-level fields are scrubbed.
-   *
-   * @default true
-   *
-   * @example
-   * ```typescript
-   * recursive: false  // Only scrub top-level fields
-   * ```
-   */
-  recursive?: boolean;
-}
-
-/**
- * Result of a scrub operation
- *
- * Contains the scrubbed data along with metadata about what was scrubbed.
- *
- * @template T - The type of the scrubbed data (same as input type)
- *
- * @example
- * ```typescript
- * const scrubber = new Scrubber({ fields: ['password'] });
- * const result = scrubber.scrub({ user: 'john', password: 'secret' });
- *
- * console.log(result.data);           // { user: 'john', password: '[SCRUBBED]' }
- * console.log(result.scrubbed);       // true
- * console.log(result.scrubbedPaths);  // ['password']
- * ```
- */
-export interface ScrubResult<T> {
-  /**
-   * The scrubbed data with sensitive values replaced
-   *
-   * This is a deep clone of the input with scrubbed values replaced.
-   * The original input is never mutated.
-   */
-  data: T;
-
-  /**
-   * Whether any scrubbing occurred
-   *
-   * `true` if at least one value was scrubbed, `false` if no sensitive data was found.
-   *
-   * Useful for logging or metrics to track scrubbing activity.
-   */
-  scrubbed: boolean;
-
-  /**
-   * Array of paths that were scrubbed
-   *
-   * Contains dot-notation paths for all fields that were scrubbed.
-   * Useful for debugging, auditing, or understanding what data was redacted.
-   *
-   * @example
-   * ```typescript
-   * ['password', 'user.email', 'request.headers.authorization']
-   * ```
-   */
-  scrubbedPaths: string[];
-}