@fozy-labs/rx-toolkit 0.5.4 → 0.6.0

package/dist/query/core/errors/MachineStateError.js

@@ -0,0 +1,10 @@
+/**
+ * Thrown when a Machine method requires state that doesn't exist
+ * (e.g. createPatch on a state without data, finishPatch without patchState).
+ */
+export class MachineStateError extends Error {
+    name = "MachineStateError";
+    constructor(method, detail) {
+        super(`Machine.${method}(): ${detail}`);
+    }
+}

package/dist/query/core/errors/MachineTransitionError.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Thrown when a Machine state transition is invalid for the current status.
+ */
+export declare class MachineTransitionError extends Error {
+    readonly name = "MachineTransitionError";
+    constructor(method: string, status: string);
+}

package/dist/query/core/errors/MachineTransitionError.js

@@ -0,0 +1,9 @@
+/**
+ * Thrown when a Machine state transition is invalid for the current status.
+ */
+export class MachineTransitionError extends Error {
+    name = "MachineTransitionError";
+    constructor(method, status) {
+        super(`Machine.${method}(): invalid transition from "${status}"`);
+    }
+}

package/dist/query/core/errors/index.d.ts

@@ -0,0 +1,3 @@
+export { MachineTransitionError } from "./MachineTransitionError";
+export { MachineStateError } from "./MachineStateError";
+export { CacheEntryRemovedError } from "./CacheEntryRemovedError";

package/dist/query/core/errors/index.js

@@ -0,0 +1,3 @@
+export { MachineTransitionError } from "./MachineTransitionError";
+export { MachineStateError } from "./MachineStateError";
+export { CacheEntryRemovedError } from "./CacheEntryRemovedError";

package/dist/query/core/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./api";
+export * from "./errors";
+export * from "./resource";
+export * from "./command";
+export * from "./machine";
+export * from "./cache";
+export * from "./snapshoter";
+export * from "./syncer";

package/dist/query/core/index.js

@@ -0,0 +1,8 @@
+export * from "./api";
+export * from "./errors";
+export * from "./resource";
+export * from "./command";
+export * from "./machine";
+export * from "./cache";
+export * from "./snapshoter";
+export * from "./syncer";

package/dist/query/core/machine/Machine.d.ts

@@ -0,0 +1,21 @@
+import { MachineError } from "./MachineError";
+import { MachinePending } from "./MachinePending";
+import { MachineRefreshError } from "./MachineRefreshError";
+import { MachineRefreshing } from "./MachineRefreshing";
+import { MachineSuccess } from "./MachineSuccess";
+export { MachineBase } from "./MachineBase";
+/**
+ * Union of all Machine subtypes.
+ *
+ * Backward-compatible: existing code typed as `Machine<A,D>` still works
+ * because all subtypes extend `MachineBase<A,D>` and carry the same `.state` shape.
+ */
+export type Machine<TArgs, TData> = MachinePending<TArgs, TData> | MachineSuccess<TArgs, TData> | MachineError<TArgs, TData> | MachineRefreshing<TArgs, TData> | MachineRefreshError<TArgs, TData>;
+export declare namespace Machine {
+    function pending<TArgs, TData>(args: TArgs): MachinePending<TArgs, TData>;
+    function fromSnapshot<TArgs, TData>(snapshot: {
+        args: TArgs;
+        data: TData;
+        updatedAt: number;
+    }, isStale?: boolean): MachineSuccess<TArgs, TData> | MachineRefreshing<TArgs, TData>;
+}

package/dist/query/core/machine/Machine.js

@@ -0,0 +1,42 @@
+import { MachinePending } from "./MachinePending";
+import { MachineRefreshing } from "./MachineRefreshing";
+import { MachineSuccess } from "./MachineSuccess";
+export { MachineBase } from "./MachineBase";
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export var Machine;
+(function (Machine) {
+    function pending(args) {
+        const state = {
+            status: "pending",
+            args,
+            data: null,
+            error: null,
+            updatedAt: null,
+        };
+        return new MachinePending(state);
+    }
+    Machine.pending = pending;
+    function fromSnapshot(snapshot, isStale = false) {
+        if (isStale) {
+            const state = {
+                status: "refreshing",
+                args: snapshot.args,
+                data: snapshot.data,
+                error: null,
+                updatedAt: snapshot.updatedAt,
+                patchState: null,
+            };
+            return new MachineRefreshing(state);
+        }
+        const state = {
+            status: "success",
+            args: snapshot.args,
+            data: snapshot.data,
+            error: null,
+            updatedAt: snapshot.updatedAt,
+            patchState: null,
+        };
+        return new MachineSuccess(state);
+    }
+    Machine.fromSnapshot = fromSnapshot;
+})(Machine || (Machine = {}));

package/dist/query/core/machine/MachineBase.d.ts

@@ -0,0 +1,31 @@
+import type { IPatchHandle, TMachineState } from "../../../query/types";
+/**
+ * Base class for the Machine state machine.
+ *
+ * Provides all transition methods with runtime guards.
+ * Subtypes extend this and override their valid transitions with narrower return types.
+ * Invalid transitions inherited from MachineBase throw MachineTransitionError/MachineStateError.
+ */
+export declare class MachineBase<TArgs, TData> {
+    readonly state: TMachineState<TArgs, TData>;
+    protected constructor(state: TMachineState<TArgs, TData>);
+    /** pending → success */
+    success(data: TData): MachineBase<TArgs, TData>;
+    /** pending → error, refreshing → refresh-error */
+    fail(error: unknown): MachineBase<TArgs, TData>;
+    /** success → refreshing, refresh-error → refreshing */
+    refresh(): MachineBase<TArgs, TData>;
+    /** error → pending */
+    retry(): MachineBase<TArgs, TData>;
+    /** refreshing → success (replays patches on new data) */
+    rebase(data: TData): MachineBase<TArgs, TData>;
+    /** Create an optimistic patch (success, refreshing, refresh-error) */
+    createPatch(patchFn: (data: TData) => void, onSettle?: () => void): {
+        machine: MachineBase<TArgs, TData>;
+        handle: IPatchHandle;
+    };
+    /** Process all settled patches up to the first pending one */
+    finishPatch(): MachineBase<TArgs, TData>;
+    /** Process all settled patches (continues past pending) */
+    finishAllPatches(): MachineBase<TArgs, TData>;
+}

package/dist/query/core/machine/MachineBase.js

@@ -0,0 +1,176 @@
+import { MachineStateError, MachineTransitionError } from "../errors";
+import { createPatches } from "../patcher";
+import { hasData, processAllPatches, processPatches, replayPatches } from "./machine-helpers";
+/**
+ * Base class for the Machine state machine.
+ *
+ * Provides all transition methods with runtime guards.
+ * Subtypes extend this and override their valid transitions with narrower return types.
+ * Invalid transitions inherited from MachineBase throw MachineTransitionError/MachineStateError.
+ */
+export class MachineBase {
+    state;
+    constructor(state) {
+        this.state = state;
+    }
+    // ==================== Transition Methods ====================
+    /** pending → success */
+    success(data) {
+        if (this.state.status !== "pending") {
+            throw new MachineTransitionError("success", this.state.status);
+        }
+        const state = {
+            status: "success",
+            args: this.state.args,
+            data,
+            error: null,
+            updatedAt: Date.now(),
+            patchState: null,
+        };
+        return new MachineBase(state);
+    }
+    /** pending → error, refreshing → refresh-error */
+    fail(error) {
+        if (this.state.status === "pending") {
+            const state = {
+                status: "error",
+                args: this.state.args,
+                data: null,
+                error,
+                updatedAt: null,
+            };
+            return new MachineBase(state);
+        }
+        if (this.state.status === "refreshing") {
+            const state = {
+                status: "refresh-error",
+                args: this.state.args,
+                data: this.state.data,
+                error,
+                updatedAt: this.state.updatedAt,
+                patchState: this.state.patchState,
+            };
+            return new MachineBase(state);
+        }
+        throw new MachineTransitionError("fail", this.state.status);
+    }
+    /** success → refreshing, refresh-error → refreshing */
+    refresh() {
+        if (this.state.status === "success") {
+            const state = {
+                status: "refreshing",
+                args: this.state.args,
+                data: this.state.data,
+                error: null,
+                updatedAt: this.state.updatedAt,
+                patchState: this.state.patchState,
+            };
+            return new MachineBase(state);
+        }
+        if (this.state.status === "refresh-error") {
+            const state = {
+                status: "refreshing",
+                args: this.state.args,
+                data: this.state.data,
+                error: null,
+                updatedAt: this.state.updatedAt,
+                patchState: this.state.patchState,
+            };
+            return new MachineBase(state);
+        }
+        throw new MachineTransitionError("refresh", this.state.status);
+    }
+    /** error → pending */
+    retry() {
+        if (this.state.status !== "error") {
+            throw new MachineTransitionError("retry", this.state.status);
+        }
+        const state = {
+            status: "pending",
+            args: this.state.args,
+            data: null,
+            error: null,
+            updatedAt: null,
+        };
+        return new MachineBase(state);
+    }
+    /** refreshing → success (replays patches on new data) */
+    rebase(data) {
+        if (this.state.status !== "refreshing") {
+            throw new MachineTransitionError("rebase", this.state.status);
+        }
+        const patchState = this.state.patchState;
+        // No patches → straight to success
+        if (!patchState) {
+            const state = {
+                status: "success",
+                args: this.state.args,
+                data,
+                error: null,
+                updatedAt: Date.now(),
+                patchState: null,
+            };
+            return new MachineBase(state);
+        }
+        // Replay pending patches on new base
+        return new MachineBase(replayPatches(this.state, "success", data, patchState.patches, Date.now()));
+    }
+    // ==================== Patch Methods ====================
+    /** Create an optimistic patch (success, refreshing, refresh-error) */
+    createPatch(patchFn, onSettle) {
+        if (!hasData(this.state)) {
+            throw new MachineStateError("createPatch", `invalid state "${this.state.status}"`);
+        }
+        const currentData = this.state.data;
+        const [nextData, forward, inverse] = createPatches(currentData, patchFn);
+        const entry = {
+            forward,
+            inverse,
+            status: "pending",
+        };
+        const existingPatches = this.state.patchState?.patches ?? [];
+        const originalData = this.state.patchState?.originalData ?? currentData;
+        const newPatchState = {
+            originalData,
+            patches: [...existingPatches, entry],
+            isConsistencyViolation: false,
+        };
+        const newState = {
+            ...this.state,
+            data: nextData,
+            patchState: newPatchState,
+        };
+        let isSettled = false;
+        const handle = {
+            commit: () => {
+                if (isSettled)
+                    return;
+                isSettled = true;
+                entry.status = "committed";
+                onSettle?.();
+            },
+            abort: () => {
+                if (isSettled)
+                    return;
+                isSettled = true;
+                entry.status = "aborted";
+                onSettle?.();
+            },
+        };
+        return { machine: new MachineBase(newState), handle };
+    }
+    /** Process all settled patches up to the first pending one */
+    finishPatch() {
+        if (!hasData(this.state) || !this.state.patchState) {
+            throw new MachineStateError("finishPatch", "no active patchState");
+        }
+        return new MachineBase(processPatches(this.state, this.state.patchState));
+    }
+    /** Process all settled patches (continues past pending) */
+    finishAllPatches() {
+        if (!hasData(this.state) || !this.state.patchState) {
+            throw new MachineStateError("finishAllPatches", "no active patchState");
+        }
+        return new MachineBase(processAllPatches(this.state, this.state.patchState));
+    }
+}

package/dist/query/core/machine/MachineError.d.ts

@@ -0,0 +1,10 @@
+import type { TErrorState } from "../../../query/types";
+import { MachineBase } from "./MachineBase";
+import { MachinePending } from "./MachinePending";
+export declare class MachineError<TArgs, TData> extends MachineBase<TArgs, TData> {
+    readonly status: "error";
+    readonly state: TErrorState<TArgs>;
+    constructor(state: TErrorState<TArgs>);
+    /** error → pending */
+    retry(): MachinePending<TArgs, TData>;
+}

package/dist/query/core/machine/MachineError.js

@@ -0,0 +1,19 @@
+import { MachineBase } from "./MachineBase";
+import { MachinePending } from "./MachinePending";
+export class MachineError extends MachineBase {
+    status = "error";
+    constructor(state) {
+        super(state);
+    }
+    /** error → pending */
+    retry() {
+        const state = {
+            status: "pending",
+            args: this.state.args,
+            data: null,
+            error: null,
+            updatedAt: null,
+        };
+        return new MachinePending(state);
+    }
+}

package/dist/query/core/machine/MachinePending.d.ts

@@ -0,0 +1,13 @@
+import type { TPendingState } from "../../../query/types";
+import { MachineBase } from "./MachineBase";
+import { MachineError } from "./MachineError";
+import { MachineSuccess } from "./MachineSuccess";
+export declare class MachinePending<TArgs, TData> extends MachineBase<TArgs, TData> {
+    readonly status: "pending";
+    readonly state: TPendingState<TArgs>;
+    constructor(state: TPendingState<TArgs>);
+    /** pending → success */
+    success(data: TData): MachineSuccess<TArgs, TData>;
+    /** pending → error */
+    fail(error: unknown): MachineError<TArgs, TData>;
+}

package/dist/query/core/machine/MachinePending.js

@@ -0,0 +1,32 @@
+import { MachineBase } from "./MachineBase";
+import { MachineError } from "./MachineError";
+import { MachineSuccess } from "./MachineSuccess";
+export class MachinePending extends MachineBase {
+    status = "pending";
+    constructor(state) {
+        super(state);
+    }
+    /** pending → success */
+    success(data) {
+        const state = {
+            status: "success",
+            args: this.state.args,
+            data,
+            error: null,
+            updatedAt: Date.now(),
+            patchState: null,
+        };
+        return new MachineSuccess(state);
+    }
+    /** pending → error */
+    fail(error) {
+        const state = {
+            status: "error",
+            args: this.state.args,
+            data: null,
+            error,
+            updatedAt: null,
+        };
+        return new MachineError(state);
+    }
+}

package/dist/query/core/machine/MachineRefreshError.d.ts

@@ -0,0 +1,12 @@
+import type { TRefreshErrorState } from "../../../query/types";
+import type { TDataState } from "./machine-helpers";
+import { MachineRefreshing } from "./MachineRefreshing";
+import { MachineWithData } from "./MachineWithData";
+export declare class MachineRefreshError<TArgs, TData> extends MachineWithData<TArgs, TData> {
+    readonly status: "refresh-error";
+    readonly state: TRefreshErrorState<TArgs, TData>;
+    constructor(state: TRefreshErrorState<TArgs, TData>);
+    protected withState(state: TDataState<TArgs, TData>): this;
+    /** refresh-error → refreshing */
+    refresh(): MachineRefreshing<TArgs, TData>;
+}

package/dist/query/core/machine/MachineRefreshError.js

@@ -0,0 +1,23 @@
+import { MachineRefreshing } from "./MachineRefreshing";
+import { MachineWithData } from "./MachineWithData";
+export class MachineRefreshError extends MachineWithData {
+    status = "refresh-error";
+    constructor(state) {
+        super(state);
+    }
+    withState(state) {
+        return new MachineRefreshError(state);
+    }
+    /** refresh-error → refreshing */
+    refresh() {
+        const state = {
+            status: "refreshing",
+            args: this.state.args,
+            data: this.state.data,
+            error: null,
+            updatedAt: this.state.updatedAt,
+            patchState: this.state.patchState,
+        };
+        return new MachineRefreshing(state);
+    }
+}

package/dist/query/core/machine/MachineRefreshing.d.ts

@@ -0,0 +1,15 @@
+import type { TRefreshingState } from "../../../query/types";
+import type { TDataState } from "./machine-helpers";
+import { MachineRefreshError } from "./MachineRefreshError";
+import { MachineSuccess } from "./MachineSuccess";
+import { MachineWithData } from "./MachineWithData";
+export declare class MachineRefreshing<TArgs, TData> extends MachineWithData<TArgs, TData> {
+    readonly status: "refreshing";
+    readonly state: TRefreshingState<TArgs, TData>;
+    constructor(state: TRefreshingState<TArgs, TData>);
+    protected withState(state: TDataState<TArgs, TData>): this;
+    /** refreshing → success (replays patches on new data) */
+    rebase(data: TData): MachineSuccess<TArgs, TData>;
+    /** refreshing → refresh-error */
+    fail(error: unknown): MachineRefreshError<TArgs, TData>;
+}

package/dist/query/core/machine/MachineRefreshing.js

@@ -0,0 +1,43 @@
+import { replayPatches } from "./machine-helpers";
+import { MachineRefreshError } from "./MachineRefreshError";
+import { MachineSuccess } from "./MachineSuccess";
+import { MachineWithData } from "./MachineWithData";
+export class MachineRefreshing extends MachineWithData {
+    status = "refreshing";
+    constructor(state) {
+        super(state);
+    }
+    withState(state) {
+        return new MachineRefreshing(state);
+    }
+    /** refreshing → success (replays patches on new data) */
+    rebase(data) {
+        const patchState = this.state.patchState;
+        if (!patchState) {
+            const state = {
+                status: "success",
+                args: this.state.args,
+                data,
+                error: null,
+                updatedAt: Date.now(),
+                patchState: null,
+            };
+            return new MachineSuccess(state);
+        }
+        // Replay pending patches on new base
+        const resultState = replayPatches(this.state, "success", data, patchState.patches, Date.now());
+        return new MachineSuccess(resultState);
+    }
+    /** refreshing → refresh-error */
+    fail(error) {
+        const state = {
+            status: "refresh-error",
+            args: this.state.args,
+            data: this.state.data,
+            error,
+            updatedAt: this.state.updatedAt,
+            patchState: this.state.patchState,
+        };
+        return new MachineRefreshError(state);
+    }
+}

package/dist/query/core/machine/MachineSuccess.d.ts

@@ -0,0 +1,12 @@
+import type { TSuccessState } from "../../../query/types";
+import type { TDataState } from "./machine-helpers";
+import { MachineRefreshing } from "./MachineRefreshing";
+import { MachineWithData } from "./MachineWithData";
+export declare class MachineSuccess<TArgs, TData> extends MachineWithData<TArgs, TData> {
+    readonly status: "success";
+    readonly state: TSuccessState<TArgs, TData>;
+    constructor(state: TSuccessState<TArgs, TData>);
+    protected withState(state: TDataState<TArgs, TData>): this;
+    /** success → refreshing */
+    refresh(): MachineRefreshing<TArgs, TData>;
+}

package/dist/query/core/machine/MachineSuccess.js

@@ -0,0 +1,23 @@
+import { MachineRefreshing } from "./MachineRefreshing";
+import { MachineWithData } from "./MachineWithData";
+export class MachineSuccess extends MachineWithData {
+    status = "success";
+    constructor(state) {
+        super(state);
+    }
+    withState(state) {
+        return new MachineSuccess(state);
+    }
+    /** success → refreshing */
+    refresh() {
+        const state = {
+            status: "refreshing",
+            args: this.state.args,
+            data: this.state.data,
+            error: null,
+            updatedAt: this.state.updatedAt,
+            patchState: this.state.patchState,
+        };
+        return new MachineRefreshing(state);
+    }
+}

package/dist/query/core/machine/MachineWithData.d.ts

@@ -0,0 +1,25 @@
+import type { IPatchHandle, TPatchState } from "../../../query/types";
+import { type TDataState } from "./machine-helpers";
+import { MachineBase } from "./MachineBase";
+export type TPatchCreateResult<TMachine> = {
+    machine: TMachine;
+    handle: IPatchHandle;
+};
+/**
+ * Abstract intermediate base for data-bearing machine states (success, refreshing, refresh-error).
+ *
+ * Carries `data`, `updatedAt`, `patchState` and all patch methods.
+ * Concrete subtypes (MachineSuccess, MachineRefreshing, MachineRefreshError)
+ * extend this and implement `withState` to preserve their identity on transitions.
+ */
+export declare abstract class MachineWithData<TArgs, TData> extends MachineBase<TArgs, TData> {
+    readonly state: TDataState<TArgs, TData>;
+    protected constructor(state: TDataState<TArgs, TData>);
+    get data(): TData;
+    get updatedAt(): number;
+    get patchState(): TPatchState<TData> | null;
+    protected abstract withState(state: TDataState<TArgs, TData>): this;
+    createPatch(patchFn: (data: TData) => void, onSettle?: () => void): TPatchCreateResult<this>;
+    finishPatch(): this;
+    finishAllPatches(): this;
+}

package/dist/query/core/machine/MachineWithData.js

@@ -0,0 +1,73 @@
+import { MachineStateError } from "../errors";
+import { createPatches } from "../patcher";
+import { processAllPatches, processPatches, withDataState } from "./machine-helpers";
+import { MachineBase } from "./MachineBase";
+/**
+ * Abstract intermediate base for data-bearing machine states (success, refreshing, refresh-error).
+ *
+ * Carries `data`, `updatedAt`, `patchState` and all patch methods.
+ * Concrete subtypes (MachineSuccess, MachineRefreshing, MachineRefreshError)
+ * extend this and implement `withState` to preserve their identity on transitions.
+ */
+export class MachineWithData extends MachineBase {
+    constructor(state) {
+        super(state);
+    }
+    get data() {
+        return this.state.data;
+    }
+    get updatedAt() {
+        return this.state.updatedAt;
+    }
+    get patchState() {
+        return this.state.patchState;
+    }
+    // ==================== Patch Methods ====================
+    createPatch(patchFn, onSettle) {
+        const currentData = this.state.data;
+        const [nextData, forward, inverse] = createPatches(currentData, patchFn);
+        const entry = {
+            forward,
+            inverse,
+            status: "pending",
+        };
+        const existingPatches = this.state.patchState?.patches ?? [];
+        const originalData = this.state.patchState?.originalData ?? currentData;
+        const newPatchState = {
+            originalData,
+            patches: [...existingPatches, entry],
+            isConsistencyViolation: false,
+        };
+        const newState = withDataState(this.state, nextData, newPatchState);
+        let isSettled = false;
+        const handle = {
+            commit: () => {
+                if (isSettled)
+                    return;
+                isSettled = true;
+                entry.status = "committed";
+                onSettle?.();
+            },
+            abort: () => {
+                if (isSettled)
+                    return;
+                isSettled = true;
+                entry.status = "aborted";
+                onSettle?.();
+            },
+        };
+        return { machine: this.withState(newState), handle };
+    }
+    finishPatch() {
+        if (!this.state.patchState) {
+            throw new MachineStateError("finishPatch", "no active patchState");
+        }
+        return this.withState(processPatches(this.state, this.state.patchState));
+    }
+    finishAllPatches() {
+        if (!this.state.patchState) {
+            throw new MachineStateError("finishAllPatches", "no active patchState");
+        }
+        return this.withState(processAllPatches(this.state, this.state.patchState));
+    }
+}

package/dist/query/core/machine/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./Machine";
+export * from "./MachineBase";
+export * from "./MachinePending";
+export * from "./MachineSuccess";
+export * from "./MachineError";
+export * from "./MachineRefreshing";
+export * from "./MachineRefreshError";
+export * from "./MachineWithData";
+export * from "./machine-helpers";