controlled-proxy

controlledProxy allows the behavior of any object to be modified & controlled non-destructively at runtime.

The developer can:

Alter the proxy's endpoint controls at runtime.
Specify a context-aware handler for disabled endpoints, also at runtime.
Create multiple proxies of an underlying object, each controlled differently.
Inject proxies into dependent code & control them from the outside.

Easy use case:

You have a utility library with extensive logging.
You consume that library from an application that uses a custom logger like winston.
You want your utility library also to log to winston.
You normally want debug logging from the utility library disabled, even when it is enabed in the outer application, but you want to enable it selectively to help debug the outer app.

API Documentation • CHANGELOG

Installation

npm install @karmaniverous/controlled-proxy

Basic Usage

The controlledProxy function creates a type-safe proxy of any object.

The options parameter is an object with the following properties:

Property	Type	Default	Description
`defaultControls`	`Record<PropertyKey, boolean>`	`{}`	A map of controlled property keys to boolean values. When this value is `true` or the property is uncontrolled, the property will behave normally. When this value is false, the property will execute the disabled member handler or return `undefined`.
`defaultDisabledMemberHandler`	`DisabledMemberHandler`	`() => undefined`	A function that is called when a disabled controlled property is accessed.
`target`	`object`	required	The object to proxy.

Example

import { controlledProxy } from '@karmaniverous/controlled-proxy';

// Create a controlled console logger. Info messages are disabled by default.
const controlledConsoleLogger = controlledProxy({
  defaultControls: { debug: true, info: false },
  target: console,
});

// Log messages.
controlledConsoleLogger.debug('debug log');
controlledConsoleLogger.info('info log');
// > debug log

Runtime Control

The proxy object has two special properties, keyed with symbols that can be imported from the package:

Property	Type	Description
`[controlProp]`	`Record<PropertyKey, boolean>`	A map of controlled property keys to boolean values. When this value is `true` or the property is uncontrolled, the property will behave normally. When this value is false, the property will execute the disabled member handler or return `undefined`.
`[disabledMemberHandlerProp]`	`DisabledMemberHandler`	A function that is called when a disabled controlled property is accessed. Defaults to `() => undefined`.

Example

import {
  controlledProxy,
  controlProp,
  disabledMemberHandlerProp,
} from '@karmaniverous/controlled-proxy';

// Create a controlled console logger. Info messages are disabled by default.
const controlledConsoleLogger = controlledProxy({
  defaultControls: { debug: true, info: false },
  target: console,
});

// Disable debug messages & enable info messages at runtime.
controlledConsoleLogger[controlProp].debug = false;
controlledConsoleLogger[controlProp].info = true;

// Log messages.
controlledConsoleLogger.debug('debug log');
controlledConsoleLogger.info('info log');
// > info log

// Change the disabled member handler.
controlledConsoleLogger[disabledMemberHandlerProp] = (
  target: Console,
  prop: PropertyKey,
) => target.log(`Accessed disabled member: ${prop.toString()}`);

// Log messages again.
controlledConsoleLogger.debug('debug log');
controlledConsoleLogger.info('info log');
// > Accessed disabled member: debug
// > info log

Proxy Injection

Here's an example of the real power of the library: let's inject a controlled proxy into a class!

Example

import { controlledProxy, controlProp } from '@karmaniverous/controlled-proxy';

// Create a class that accepts a proxied logger as a constructor argument.
class MyClass {
  // Proxied logger must be compatible with console.debug & console.info.
  constructor(private logger: Pick<Console, 'debug' | 'info'>) {}

  // Exercise the proxied logger.
  myMethod() {
    this.logger.debug('debug log');
    this.logger.info('info log');
  }
}

// Create a controlled console logger, with all messages enabled by default
// and a custom disabled member handler.
const controlledConsoleLogger = controlledProxy({
  defaultControls: { debug: false, info: true },
  defaultDisabledMemberHandler: (target: Console, prop: PropertyKey) =>
    target.log(`Accessed disabled member: ${prop.toString()}`),
  target: console,
});

// Instantiate the class with the controlled console logger.
const myConsoleInstance = new MyClass(controlledConsoleLogger);

// Disable console debug messages at runtime.
controlledConsoleLogger[controlProp].debug = false;

// Exercise the proxied console logger from within the class.
myConsoleInstance.myMethod();
// > Accessed disabled member: debug
// > info log

// Create an equivalent controlled winston logger, with all messages enabled by
// default and a custom disabled member handler.
import { createLogger, type Logger } from 'winston';

const controlledWinstonLogger = controlledProxy({
  defaultControls: { debug: true, info: true },
  defaultDisabledMemberHandler: (target: Logger, prop: PropertyKey) =>
    target.log('warn', `Accessed disabled member: ${prop.toString()}`),
  target: createLogger(),
});

// Instantiate the class again with the controlled winston logger.
const myWinstonInstance = new MyClass(controlledWinstonLogger);

// Disable winston debug messages at runtime.
controlledWinstonLogger[controlProp].debug = false;

// Exercise the proxied winston logger from within the class.
myWinstonInstance.myMethod();
// > [winston] { "level":"warn", "message":"Accessed disabled member: debug" }
// > [winston] { "level":"info", "message":"info log" }

Built for you with ❤️ on Bali! Find more great tools & templates on my GitHub Profile.