@dffrs/spy

SPY

This library provides a TypeScript mixin that adds observable behavior to a class, allowing observers to listen for changes in properties and trigger effects before or after method calls. The library uses TypeScript's type system to ensure type safety and flexibility.

Table of Contents

• Installation
• Usage
  • Creating an Observable Class
  • Observing Property Changes
  • Listening to Method Calls
  • Removing Observers and Listeners
• API Reference
  • observe
  • beforeCalling
  • afterCalling
  • removeLast
  • remove

Installation

You can install the library using npm:

npm install spy

Usage

Creating an Observable Class.

To create an observable class, use the Spy mixin function:

import { Spy } from "spy";

class MyClass {
  myProperty: string = "initial value";

  myMethod() {
    console.log("myMethod called");
  }
}

const ObservableMyClass = Spy(MyClass);
const instance = new ObservableMyClass();

Observing Property Changes

You can observe changes to specific properties or all properties:

instance.observe("myProperty", (newValue, oldValue) => {
  console.log(`myProperty changed from ${oldValue} to ${newValue}`);
});

instance.observe("all", (newValue, oldValue) => {
  console.log(`A property changed from ${oldValue} to ${newValue}`);
});

Listening to Method Calls

You can add effects to be executed before or after specific method calls:

instance.beforeCalling("myMethod", () => {
  console.log("Before myMethod");
});

instance.afterCalling("myMethod", () => {
  console.log("After myMethod");
});

Removing Observers and Listeners

You can remove the last added observer for a specific property or all properties:

instance.removeLast("myProperty");
instance.removeLast("all");

You can also remove a specific observer or listener:

instance.remove("myProperty", observerFunction);
instance.remove("all", observerFunction);

API Reference

observe

The observe method adds an observer for a specific property or all properties.

observe<V extends keyof T | "all">(
  prop: V,
  effect: V extends "all"
    ? (data: ExcludeFunction<T[keyof T]>, oldData: ExcludeFunction<T[keyof T]>) => void
    : (data: ExcludeFunction<ExtractType<T, V>>, oldData: ExcludeFunction<ExtractType<T, V>>) => void
): void;

beforeCalling

The beforeCalling method adds an effect to be executed before a specific method is called.

beforeCalling(
  method: PickFunctionNames<T>,
  effect: () => void
): void;

afterCalling

The afterCalling method adds an effect to be executed after a specific method is called.

afterCalling(
  method: PickFunctionNames<T>,
  effect: () => void
): void;

removeLast

The removeLast method removes the last added observer for a specific property or all properties.

removeLast<V extends keyof T | "all">(
  prop: V
): boolean;

remove

The remove method removes a specific observer for a property or all properties.

remove<V extends keyof T | "all">(
  prop: V,
  effect: (...args: any[]) => unknown,
  comparator?: (
    registeredMethod: (...args: any[]) => unknown,
    toRemoveMethod: (...args: any[]) => unknown
  ) => boolean
): boolean;