@yoltra/core 0.6.0 → 0.8.0

package/dist/types/store/fingerprint.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Content fingerprints for event deduplication.
+ *
+ * @remarks
+ * Extracted from `Store.ts` following the `matching.ts` / `paths.ts` precedent: nothing here
+ * touches an instance field.
+ *
+ * The old fingerprint was `channel::type::JSON.stringify(payload)`, which produced two
+ * inconsistent failures on the one path whose entire job is deciding whether two payloads are
+ * the same. A `Map`, `Set` or typed array stringifies to `{}`, so **distinct payloads
+ * collided and the second event was silently swallowed** - precisely the behaviour the README
+ * says Yoltra refuses to do by default. A `BigInt` or a cycle threw, hit a timestamp fallback,
+ * and was never deduped at all.
+ *
+ * `encodeState` already produces a faithful, JSON-stringifiable representation of all of
+ * those, so fingerprinting through it makes content dedup mean what it says.
+ *
+ * @module
+ */
+/**
+ * JSON with plain-object keys sorted, for a stable content fingerprint.
+ *
+ * @remarks
+ * Insertion order is not content: `{a:1,b:2}` and `{b:2,a:1}` are the same payload and must
+ * fingerprint alike, which `JSON.stringify` alone does not deliver.
+ *
+ * **Arrays and `Map` entries are never sorted.** Their order is semantic - `[1,2]` is not
+ * `[2,1]`, and a `Map` preserves insertion order by specification. Sorting them would make
+ * genuinely different payloads share a fingerprint, which is worse than the bug this module
+ * exists to fix: it would silently drop real events rather than merely failing to dedup.
+ *
+ * Runs over the **already-encoded** value, so `Map`, `Set`, `Date` and binary have already
+ * become plain JSON shapes and there is nothing exotic left to handle.
+ *
+ * `JSON.stringify(v, keyArray)` cannot do this: the replacer-array form applies one global
+ * key list at every depth.
+ *
+ * @internal
+ */
+export declare function stableStringify(value: unknown): string;
+/**
+ * A content fingerprint for one event.
+ *
+ * @param channel - Event channel.
+ * @param type - Event type.
+ * @param payload - Event payload.
+ * @returns A string that is equal for two events with equal content.
+ *
+ * @remarks
+ * Primitives keep a fast path, but a typed one: `String(payload)` alone made the number `1`
+ * and the string `"1"` the same event, as it did `true` and `"true"`. `null` and `undefined`
+ * are likewise distinguished, having previously shared `::null`.
+ *
+ * When the payload exceeds the node budget the fingerprint degrades to **never dedupe**
+ * rather than maybe-wrongly-dedupe. Two large payloads differing only past the cutoff would
+ * otherwise collide and the second would be dropped; refusing to dedup merely costs a
+ * duplicate, which is the safe direction and matches what already happened to payloads the
+ * old implementation could not serialize.
+ *
+ * @internal
+ */
+export declare function fingerprint(channel: string, type: string, payload: unknown): string;

package/dist/types/store/matching.d.ts

@@ -0,0 +1,49 @@
+import { EventKey, EventMapBase, EventUnion, MiddlewareFunction, MiddlewareInput, When } from '../types.js';
+/**
+ * Checks if an event matches a `When` matcher.
+ *
+ * @param when - The When matcher (or undefined for "all events").
+ * @param event - The event to check.
+ * @returns `true` if the event matches, `false` otherwise.
+ *
+ * @remarks
+ * - `undefined` or missing `when` matches ALL events.
+ * - `{ any: true }` matches ALL events.
+ * - `{ keys: [...] }` matches if event's `[channel, type]` is in the array.
+ * - `{ channel: 'x' }` matches if event's channel equals 'x'.
+ * - `{ channels: ['x', 'y'] }` matches if event's channel is in the array.
+ *
+ * @internal
+ */
+export declare function matchesWhen<EM extends EventMapBase>(when: When<EM> | undefined, event: EventUnion<EM>): boolean;
+/**
+ * Extracts the middleware function from a MiddlewareInput.
+ * Handles both raw functions (legacy) and MiddlewareSpec objects.
+ *
+ * @param input - MiddlewareInput (function or spec).
+ * @returns The middleware function.
+ *
+ * @internal
+ */
+export declare function getMiddlewareFunction<St, EM extends EventMapBase>(input: MiddlewareInput<St, EM>): MiddlewareFunction<St, EM>;
+/**
+ * Gets the `when` matcher from a MiddlewareInput.
+ *
+ * @param input - MiddlewareInput (function or spec).
+ * @returns The `when` matcher, or `undefined` for raw functions (match all).
+ *
+ * @internal
+ */
+export declare function getMiddlewareWhen<St, EM extends EventMapBase>(input: MiddlewareInput<St, EM>): When<EM> | undefined;
+/**
+ * Normalizes event targeting from `when` to an array of EventKeys.
+ *
+ * @param spec - Object with an optional `when` matcher.
+ * @returns Array of `[channel, type]` pairs.
+ *
+ * @internal
+ */
+export declare function normalizeEventKeys<EM extends EventMapBase>(spec: {
+    when?: When<EM>;
+    events?: ReadonlyArray<EventKey<EM>>;
+}): ReadonlyArray<EventKey<EM>>;

package/dist/types/store/paths.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Reading and expanding dotted state paths.
+ *
+ * @remarks
+ * Moved out of `Store.ts` unchanged. Neither function touched an instance field.
+ *
+ * `Store` still exposes both as members, and deliberately so. `Store.buildAncestorPaths` is
+ * public API that appears in the committed reference, and `getAtPath` is replaced on the
+ * instance by a test that counts the walks a change description costs, so the internal callers
+ * have to keep reaching it through `this`.
+ *
+ * @module
+ */
+/**
+ * Reads a dotted path from an object (supports numeric array indices via string keys).
+ *
+ * @param obj - Root object (slice or value).
+ * @param path - Dotted path; leading dot is ignored.
+ * @returns The value at the path, or `undefined`.
+ *
+ * @internal
+ */
+export declare function getAtPath(obj: any, path: string): any;
+/**
+ * Builds ancestor paths for a dotted path.
+ *
+ * For `"a.b.c"`, returns `["a", "a.b", "a.b.c"]`. Leading dots are trimmed.
+ *
+ * @param path - Dotted path string.
+ * @returns Array of ancestor paths.
+ *
+ * @example
+ * ```ts
+ * buildAncestorPaths('x.y.z'); // ['x','x.y','x.y.z']
+ * ```
+ *
+ * @public
+ */
+export declare function buildAncestorPaths(path: string): string[];

package/dist/types/store/performCall.d.ts

@@ -0,0 +1,15 @@
+import { DeepReadonly, EffectSpec, EmitOptions, EmitResult, EventMapBase, EventUnion } from '../types.js';
+import { CallHandle, CallOptions } from './call.js';
+/**
+ * What `performCall` needs from the store.
+ *
+ * @remarks
+ * Three members, named rather than structural over the whole class, because three is few enough
+ * that naming them documents the coupling instead of hiding it.
+ */
+export interface CallDeps<St, EM extends EventMapBase> {
+    readonly idFactory: () => string;
+    readonly registerEffect: (spec: EffectSpec<DeepReadonly<St>, EM>) => () => void;
+    readonly emit: <C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, payload: EM[C][T], opts?: EmitOptions) => Promise<EmitResult>;
+}
+export declare function performCall<St, EM extends EventMapBase, C extends keyof EM & string, T extends keyof EM[C] & string>(deps: CallDeps<St, EM>, channel: C, type: T, payload: EM[C][T], opts: CallOptions<EM>): CallHandle<EventUnion<EM>, EventUnion<EM>>;

package/dist/types/store/rejection.d.ts

@@ -6,8 +6,8 @@
  *
  * @remarks
  * `Symbol.for` rather than `Symbol()`, so the brand survives two copies of this package meeting
- * at runtime — a duplicated dependency, a federated bundle, a consumer that pinned an older
- * minor. With a unique symbol the check would silently answer `false` across that boundary and a
+ * at runtime — a duplicated dependency, a bundle that inlined a second copy, a consumer that
+ * pinned an older minor. With a unique symbol the check would silently answer `false` across that boundary and a
  * refusal would read as ordinary state, which is the failure this whole feature exists to end.
  *
  * @internal