Nostalgic Punchcard Missing

    @harlem/extension-trace
    TypeScript icon, indicating that this package has built-in type declarations

    2.3.6 • Public • Published

    Harlem Trace Extension

    npm

    This is the official trace extension for Harlem. The trace extension adds the ability to trace granular changes to state. It is useful for detailed auditing of state changes or as a building block of undo/redo functionality.

    Getting Started

    Follow the steps below to get started using the trace extension.

    Installation

    Before installing this extension make sure you have installed @harlem/core.

    yarn add @harlem/extension-trace
    # or
    npm install @harlem/extension-trace

    Registration

    To get started simply register this extension with the store you wish to extend.

    import traceExtension from '@harlem/extension-trace';
    
    import {
        createStore
    } from '@harlem/core';
    
    const STATE = {
        firstName: 'Jane',
        lastName: 'Smith'
    };
    
    const {
        state,
        getter,
        mutation,
        startTrace,
        stopTrace,
        onTraceResult,
    } = createStore('example', STATE, {
        extensions: [
            traceExtension({
                autoStart: true,
                debug: true,
            })
        ]
    });

    The trace extension adds several new methods to the store instance (highlighted above).

    Usage

    Options

    The storage extension method accepts an options object with the following properties:

    • autoStart: boolean - Indicates whether to start tracing automatically after the store is created. Default value is false.
    • debug: boolean - Enables debug mode. This logs all trace results to the console. Default value is false.

    Manually starting/stopping tracing

    Tracing can be manually started or stopped at any time using the startTrace and stopTrace methods. The startTrace method accepts an optional gates parameter which is an array of strings representing the proxy gates to catch during tracing. The default gate is set.

    See here for a full list of proxy gates available.

    ::: tip Note The only gates currently available for tracing are get, set and deleteProperty. :::

    Handling trace results

    The onTraceResult method lets you handle the result when one of the specified gates is accessed during a trace. The method takes a single function parameter with a result as it's only argument.

    const listener = onTraceResult(result => console.log(result));
    
    // To cleanup:
    listener.dispose();

    The result object has the following properties:

    • path: string - The path at which the trace gate was triggered. Eg. /user/details/roles[0]/id.
    • gate: string - The gate this result was triggered for.
    • nodes: (string | number)[] - The nodes traversed when this gate was triggered. Given the above path, this value would be ['user', 'details', 'roles', 0].
    • prop: string | number - The prop that triggered the gate. Eg. id.
    • oldValue: unknown - The value before the change.
    • newValue: unknown - The value after the change.

    Install

    npm i @harlem/extension-trace

    Homepage

    harlemjs.com

    DownloadsWeekly Downloads

    21

    Version

    2.3.6

    License

    MIT

    Unpacked Size

    1.57 MB

    Total Files

    16

    Last publish

    Collaborators

    • andrewcourtice