!Min+Gzip

Pulse

> Microscopic signals with automatic dependency tracking.

Pulse signals are straightforward containers for values—no magic, no proxies, no weird tricks. They hold anything you throw at them: scalars, objects, DOM elements, functions, classes, instances... Whatever.

No need to worry about tracking dependencies in your computed values or effects—Pulse handles that automatically.

At its core, it's a simple API:

``ts
function signal(value: T): IMutableSignal;
function effect(fn: EffectFunction, onError?: ErrorCallback): CleanupFunction;
function computed(fn: () => T, onError?: ErrorCallback, type?: 'eager' | 'lazy'): ISignal; // default is "lazy"
function batch(fn: () => void): void;

type EffectFunction = () => void | (() => void);
type CleanupFunction = () => void;
type ErrorCallback = (error: any, source: any) => void;

interface ISignal {
readonly value: T;
get(): T;
peek(): T;
subscribe(run: (value: T) => void): CleanupFunction;
}

interface IMutableSignal extends ISignal {
get value(): T;
set value(newValue: T);
set(newValue: T): void;
update(updater: (value: T) => T): void;
}
`

Usage

`ts
import { signal, computed, effect } from "@elucidata/pulse";

const counter = signal(0);
const doubled = computed(() => counter.get() * 2);

effect(() => {
// You can use .get() or .value
console.log("Counter:", counter.value, "Doubled:", doubled.value);
});

counter.set(1);
// or counter.value = 1
// or counter.update(c => c + 1);
`

Installation

Pulse has no dependencies or prerequisites other than a JavaScript runtime. Bun is used for development.

To install Pulse:

`
bun add @elucidata/pulse
`

React/Preact

There are two ways to react to signal changes: using a higher-order function or a hook.

$3

`tsx
import { signal } from "@elucidata/pulse";
import { observer } from "@elucidata/pulse/react";

const counter = signal(1);

const ExampleView = observer((props) => {
return

;
});
`

$3

`tsx
import { signal } from "@elucidata/pulse";
import { useComputed } from "@elucidata/pulse/react";

const counter = signal(1);

const ExampleView = (props) => {
const count = useComputed(() => counter.value);

return

;
};
`

$3

While not recommended, you _could_ do something like this:

`tsx
import { signal } from "@elucidata/pulse";
import { useComputed } from "@elucidata/pulse/react";
import { useEffect, useMemo } from "react";

const ExampleView = (props) => {
const counter = useMemo(() => signal(1), []);
const count = useComputed(() => counter.value);

useEffect(() => {
const interval = setInterval(() => {
counter.update((prev) => prev + 1);
}, 1000);

return () => clearInterval(interval);
}, []);

return

;
};
`

Svelte

Signals comply with Svelte's store contract:

`svelte



`

Pulse View (Experimental)

Included is a tiny experimental view engine you can play with. Feedback is welcome. Pulse View is a declarative, statement-based, reactive UI toolkit.

- No Build Step: No compiler/transpiler required.
- No Virtual DOM: Live DOM nodes are created and deleted by builders.
- Signal-Driven Updates: Updates are reactions to signal values only.
- Reactive Sections: Parts of a view can be reactive when denoted with when, each, or live.

$3

Pulse View is guided by a set of high-level principles:

1. Dynamic View Management: Views in Pulse View are dynamically built and removed as needed.
2. Signal-Driven Updates: All updates within Pulse View are driven by signal reactions.
3. Modularity and Reusability: Components within Pulse View are designed to be modular and reusable.
4. Performance Optimization: Pulse View is optimized for performance, ensuring that even with dynamic view management and signal-driven updates, the application remains fast and responsive.

$3

`ts
import { view, signal, render, tags, text } from '@elucidata/pulse/view';

const { div, button } = tags;

const counter = signal(0);

const CounterView = view(() => {
Root(() => {
Button('Increment', () => counter.value++);
Button('Decrement', () => counter.value--);

div(() => {
text('Count: ');
text(counter);
});
});
});

const Root = div.design.css
padding: 1rem;
border: 0.1rem solid dodgerblue;
;

const Button = (children, onclick) => {
button({ onclick }, children);
};

const dispose = render(CounterView(), document.getElementById('app'));
`

Utilities

$3

`ts
declare function persistedSignal(
key: string,
initialValue: T,
options?: Partial>
): Signal;

interface PersistedSignalOptions {
storage: IStorage; // Defaults to globalThis.localStorage
toStorage: (value: T) => string; // Defaults to JSON.stringify
fromStorage: (value: string) => T; // Defaults to JSON.parse
}

interface IStorage {
getItem(key: string): string | null;
setItem(key: string, value: string): void;
}
`

Creates a signal that persists its value in storage (using localStorage by default). The value is serialized to a string before being stored and deserialized when retrieved. If storage is unavailable, a regular signal will be returned instead.

$3

`ts
declare function update(
state: Signal,
updater: Merger | Updater,
reportChanges?: boolean
): boolean | (keyof T)[];

type Merger = Partial | ((v: T) => Partial);
type Updater = Required | ((v: T) => T);
`

Updates a signal with a new value or partial value. If a function is provided as the updater, it receives the current value and should return the updated value. If an object is returned, it will be merged with the current value. When reportChanges is set to true`, the function returns an array of keys that were changed.

How Is This Different Than Others?

KISS — Keep It Simple, Signals. Think of it like nanostores but with automatic dependency tracking. If you need more advanced signal implementations, check out:

- Preact Signals
- MobX
- SolidJS

Contributing

We happily review contributions from the community. To be eligible for merging into Pulse, please follow these guidelines and project goals:

- Keep It Simple
- Keep It Small
- Keep It Fast
- Err on the Side of Less Code

License

_Pulse_ is licensed under the MIT License.