@continuum-js/std 0.3.0

package/README.md

@@ -0,0 +1,62 @@
+# @continuum-js/std
+
+Стандартная библиотека переиспользуемых FRP-комбинаторов Continuum — то, что
+нужно каждый день: тайминг, асинхронные данные, форма потоков, хелперы для
+поведений. Всё построено поверх `@continuum-js/frp` без доступа к внутренностям,
+которых ядро не отдаёт наружу.
+
+```ts
+import { resource, debounce /* … */ } from "@continuum-js/std";
+```
+
+## Тайминг
+
+Мост к настенным часам (`setTimeout`/`setInterval`). Каждый возвращает событие,
+которое гасит свой таймер в `dispose()`.
+
+|                   |                                                                 |
+| ----------------- | --------------------------------------------------------------- |
+| `debounce(e, ms)` | эмит после `ms` тишины, всплеск коалесится в последнее значение |
+| `throttle(e, ms)` | пропустить первое происшествие, затем игнорировать `ms`         |
+| `delay(e, ms)`    | сдвинуть каждое происшествие на `ms` позже                      |
+| `interval(ms)`    | источник, тикающий `1, 2, 3, …` каждые `ms`                     |
+
+## Форма потоков
+
+Производные события над графом (glitch-free, по рангам).
+
+|                          |                                                    |
+| ------------------------ | -------------------------------------------------- |
+| `filterMap(e, f)`        | map с отбрасыванием `null`/`undefined`             |
+| `pairwise(e)`            | `[prev, curr]`, начиная со второго происшествия    |
+| `partition(e, pred)`     | разбить поток на `[подходящие, остальные]`         |
+| `count(e)`               | `Behavior<number>` — сколько раз событие случилось |
+| `sampleWith(trigger, b)` | значение `b` в момент каждого `trigger`            |
+
+## Поведения
+
+|                     |                                                                |
+| ------------------- | -------------------------------------------------------------- |
+| `previous(b, init)` | поведение, отстающее на шаг (значение до последнего изменения) |
+| `distinctB(b, eq?)` | подавляет обновления, равные текущему значению                 |
+
+## Асинхронные данные (HTTP)
+
+`perform` — граница IO (§6.5): эффект бежит после закрытия момента, результат
+возвращается в сеть как данные, ошибка завёрнута в `Result`, а не выброшена.
+
+- **`resource(trigger, fetcher): Behavior<Async<T>>`** — конечный автомат
+  `idle → loading → ok | error`. Запросы нумеруются, поэтому запоздавший ответ
+  на устаревший запрос отбрасывается (last-request-wins) — декларативное решение
+  классического бага гонки ответов.
+- **`Async<T>`** — жизненный цикл запроса как первоклассные данные.
+
+```ts
+const query = debounce(input.updates, 300).filter((s) => s.length > 0);
+const users = resource(query, (q) =>
+  fetch(`/api?q=${q}`).then((r) => r.json()),
+);
+// users: Behavior<Async<User[]>>  — рисуй по users.status
+```
+
+Живой пример — [`examples/data`](../../examples/data).

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { Event, Behavior } from "@continuum-js/frp";
+/**
+ * Emit only after `ms` of quiet, coalescing a burst into its last value.
+ * (Trailing debounce.)
+ */
+export declare function debounce<A>(e: Event<A>, ms: number): Event<A>;
+/**
+ * Emit the leading occurrence immediately, then ignore further ones for `ms`.
+ * (Leading throttle / rate limit.)
+ */
+export declare function throttle<A>(e: Event<A>, ms: number): Event<A>;
+/** Shift every occurrence later by `ms`, preserving order and multiplicity. */
+export declare function delay<A>(e: Event<A>, ms: number): Event<A>;
+/** A source event ticking `1, 2, 3, …` every `ms`. Stops on `dispose()`. */
+export declare function interval(ms: number): Event<number>;
+/** Map, dropping occurrences whose result is `null`/`undefined`. */
+export declare function filterMap<A, B>(e: Event<A>, f: (a: A) => B | null | undefined): Event<B>;
+/** Pair each occurrence with the previous one; emits from the 2nd occurrence. */
+export declare function pairwise<A>(e: Event<A>): Event<[A, A]>;
+/** Split a stream by a predicate into `[matching, rest]`. */
+export declare function partition<A>(e: Event<A>, pred: (a: A) => boolean): [Event<A>, Event<A>];
+/** A behavior of how many times the event has occurred. */
+export declare function count(e: Event<unknown>): Behavior<number>;
+/** Sample `b` at each occurrence of `trigger`, discarding the trigger's value. */
+export declare function sampleWith<A, B>(trigger: Event<A>, b: Behavior<B>): Event<B>;
+/** A behavior lagging one step behind `b` (its value before the latest change). */
+export declare function previous<A>(b: Behavior<A>, init: A): Behavior<A>;
+/** A behavior that suppresses updates equal to the current value (default `Object.is`). */
+export declare function distinctB<A>(b: Behavior<A>, eq?: (x: A, y: A) => boolean): Behavior<A>;
+/** The lifecycle of an asynchronous request as first-class data. */
+export type Async<T> = {
+    status: "idle";
+} | {
+    status: "loading";
+} | {
+    status: "ok";
+    value: T;
+} | {
+    status: "error";
+    error: unknown;
+};
+/**
+ * Turn a stream of requests into a behavior tracking the async lifecycle
+ * (`idle → loading → ok | error`). Requests are stamped with a sequence number,
+ * so a slow response to a superseded request is ignored (last-request-wins) —
+ * the classic out-of-order-response bug, solved declaratively.
+ */
+export declare function resource<A, T>(trigger: Event<A>, fetcher: (arg: A) => Promise<T>): Behavior<Async<T>>;

package/dist/index.js

@@ -0,0 +1,168 @@
+// Continuum standard library (std).
+// Reusable combinators built purely on the frp core — the everyday toolkit for
+// real apps: timing, async data, stream shaping, behavior helpers. Nothing here
+// touches internals the core doesn't already expose.
+import { Event, Behavior, newEvent, perform } from "@continuum-js/frp";
+// ===========================================================================
+// Timing — bridges to the wall clock via setTimeout/setInterval. Each returns
+// an event that tears its timer down on `dispose()`.
+// ===========================================================================
+/**
+ * Emit only after `ms` of quiet, coalescing a burst into its last value.
+ * (Trailing debounce.)
+ */
+export function debounce(e, ms) {
+    const [out, fire] = newEvent();
+    let timer;
+    const un = e.listen((a) => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            fire(a);
+        }, ms);
+    });
+    out.onDispose(() => {
+        un();
+        if (timer !== undefined)
+            clearTimeout(timer);
+    });
+    return out;
+}
+/**
+ * Emit the leading occurrence immediately, then ignore further ones for `ms`.
+ * (Leading throttle / rate limit.)
+ */
+export function throttle(e, ms) {
+    const [out, fire] = newEvent();
+    let blocked = false;
+    let timer;
+    const un = e.listen((a) => {
+        if (blocked)
+            return;
+        blocked = true;
+        fire(a);
+        timer = setTimeout(() => {
+            blocked = false;
+        }, ms);
+    });
+    out.onDispose(() => {
+        un();
+        if (timer !== undefined)
+            clearTimeout(timer);
+    });
+    return out;
+}
+/** Shift every occurrence later by `ms`, preserving order and multiplicity. */
+export function delay(e, ms) {
+    const [out, fire] = newEvent();
+    const timers = new Set();
+    const un = e.listen((a) => {
+        const id = setTimeout(() => {
+            timers.delete(id);
+            fire(a);
+        }, ms);
+        timers.add(id);
+    });
+    out.onDispose(() => {
+        un();
+        for (const id of timers)
+            clearTimeout(id);
+        timers.clear();
+    });
+    return out;
+}
+/** A source event ticking `1, 2, 3, …` every `ms`. Stops on `dispose()`. */
+export function interval(ms) {
+    const [out, fire] = newEvent();
+    let n = 0;
+    const id = setInterval(() => fire(++n), ms);
+    out.onDispose(() => clearInterval(id));
+    return out;
+}
+// ===========================================================================
+// Stream shaping — derived events over the graph (glitch-free, rank-ordered).
+// ===========================================================================
+/** Map, dropping occurrences whose result is `null`/`undefined`. */
+export function filterMap(e, f) {
+    const out = new Event(e.rank + 1);
+    out.consume(e, (t, a) => {
+        const b = f(a);
+        if (b != null)
+            out.send_(t, b);
+    });
+    return out;
+}
+/** Pair each occurrence with the previous one; emits from the 2nd occurrence. */
+export function pairwise(e) {
+    const out = new Event(e.rank + 1);
+    let hasPrev = false;
+    let prev;
+    out.consume(e, (t, a) => {
+        if (hasPrev)
+            out.send_(t, [prev, a]);
+        prev = a;
+        hasPrev = true;
+    });
+    return out;
+}
+/** Split a stream by a predicate into `[matching, rest]`. */
+export function partition(e, pred) {
+    return [e.filter(pred), e.filter((a) => !pred(a))];
+}
+/** A behavior of how many times the event has occurred. */
+export function count(e) {
+    return e.accum(0, (_a, n) => n + 1);
+}
+/** Sample `b` at each occurrence of `trigger`, discarding the trigger's value. */
+export function sampleWith(trigger, b) {
+    return trigger.snapshot(b, (_a, v) => v);
+}
+// ===========================================================================
+// Behavior helpers.
+// ===========================================================================
+/** A behavior lagging one step behind `b` (its value before the latest change). */
+export function previous(b, init) {
+    // At the instant of an update, `b` still samples its pre-commit (prior) value,
+    // since `hold` commits at the moment boundary.
+    return b.updates.snapshot(b, (_new, old) => old).hold(init);
+}
+/** A behavior that suppresses updates equal to the current value (default `Object.is`). */
+export function distinctB(b, eq = Object.is) {
+    const out = new Event(b.updates.rank + 1);
+    let prev = b.sampleNoTrans();
+    b.updates.listen_(out, (t, a) => {
+        if (!eq(prev, a)) {
+            prev = a;
+            out.send_(t, a);
+        }
+    });
+    return new Behavior(() => b.sampleNoTrans(), out);
+}
+/**
+ * Turn a stream of requests into a behavior tracking the async lifecycle
+ * (`idle → loading → ok | error`). Requests are stamped with a sequence number,
+ * so a slow response to a superseded request is ignored (last-request-wins) —
+ * the classic out-of-order-response bug, solved declaratively.
+ */
+export function resource(trigger, fetcher) {
+    const requests = trigger.accumE({ seq: 0, arg: null }, (arg, prev) => ({
+        seq: prev.seq + 1,
+        arg,
+    }));
+    const latest = requests.map((r) => r.seq).hold(0);
+    const responses = perform(requests, (r) => fetcher(r.arg).then((value) => ({ seq: r.seq, value })));
+    const settled = responses
+        .snapshot(latest, (res, latestSeq) => {
+        if (res.ok) {
+            if (res.value.seq !== latestSeq)
+                return null; // superseded — ignore
+            return { status: "ok", value: res.value.value };
+        }
+        return { status: "error", error: res.error };
+    })
+        .filter((s) => s !== null);
+    const loading = requests.mapTo({ status: "loading" });
+    // loading (request moment) and settled (later moment) never coincide.
+    return loading.orElse(settled).hold({ status: "idle" });
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@continuum-js/std",
+  "version": "0.3.0",
+  "description": "Continuum standard library — reusable FRP combinators (async, timing, streams)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/denislibs/continuum.git",
+    "directory": "packages/std"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@continuum-js/frp": "0.3.0"
+  }
+}