@vef-framework-react/core 2.3.0 → 2.4.1

package/dist/types/storage/uploader-machine.d.ts

@@ -0,0 +1,108 @@
+import { ResumePlan } from './resumable/plan';
+import { StateMachine, MachineContext, ActorRefFromLogic, PromiseActorLogic, NonReducibleUnknown, EventObject, MetaObject } from 'xstate';
+/**
+ * Side-effect surface the uploader statechart drives. The machine owns the
+ * lifecycle only — every phase runner closes over the `Uploader` instance
+ * that supplies it, so the chart stays a pure, domain-free transition table.
+ */
+export interface UploaderMachineDeps {
+    /**
+     * Open (fresh) or synthesise (resume) the multipart session and seed the
+     * uploader's bookkeeping. Rejection means the session never opened.
+     */
+    prepareSession: (plan: ResumePlan) => Promise<void>;
+    /**
+     * Stream every pending part through the worker pool. Rejection carries the
+     * first terminal worker error.
+     */
+    uploadParts: () => Promise<void>;
+    /**
+     * Finalize the multipart session and capture the upload result.
+     */
+    completeSession: () => Promise<void>;
+    /**
+     * Best-effort backend `abort_upload`. Must never reject for control flow —
+     * the machine lands in `aborted` either way.
+     */
+    abortSession: () => Promise<void>;
+    /**
+     * Abort the shared transport controller so in-flight HTTP requests and
+     * pending retry backoffs unwind immediately.
+     */
+    killTransport: () => void;
+    /**
+     * Record the error a phase rejected with; `start()` rejects with it once
+     * the machine reaches `failed`.
+     */
+    recordFailure: (error: unknown) => void;
+    /**
+     * Whether an abort was latched before the run started (external signal
+     * already aborted, or `abort()` called while still idle).
+     */
+    abortRequested: () => boolean;
+}
+export type UploaderEvent = {
+    type: "START";
+    plan: ResumePlan;
+} | {
+    type: "ABORT";
+};
+/**
+ * Lifecycle statechart behind `Uploader`. State names are exactly the public
+ * `UploadStatus` values — the chart IS the documented contract in
+ * `./types.ts`, and `Uploader` maps snapshots to statuses by name.
+ *
+ * Cancellation is an *event channel* (`ABORT`), not an error-instance check:
+ * a phase rejection always means failure (`onError` → `failed`, session kept
+ * alive for resume), while a caller abort always transitions to `aborting`
+ * (backend session torn down). The two can no longer be confused, even when
+ * the worker pool trips the shared controller itself to stop sibling workers
+ * after a terminal part failure.
+ */
+export declare function createUploaderMachine(deps: UploaderMachineDeps): StateMachine<MachineContext, {
+    type: "START";
+    plan: ResumePlan;
+} | {
+    type: "ABORT";
+}, {
+    [x: string]: ActorRefFromLogic<PromiseActorLogic<void, NonReducibleUnknown, EventObject>> | ActorRefFromLogic<PromiseActorLogic<void, ResumePlan, EventObject>> | undefined;
+}, {
+    src: "prepareSession";
+    logic: PromiseActorLogic<void, ResumePlan, EventObject>;
+    id: string | undefined;
+} | {
+    src: "uploadParts";
+    logic: PromiseActorLogic<void, NonReducibleUnknown, EventObject>;
+    id: string | undefined;
+} | {
+    src: "completeSession";
+    logic: PromiseActorLogic<void, NonReducibleUnknown, EventObject>;
+    id: string | undefined;
+} | {
+    src: "abortSession";
+    logic: PromiseActorLogic<void, NonReducibleUnknown, EventObject>;
+    id: string | undefined;
+}, {
+    type: "recordFailure";
+    params: {
+        error: unknown;
+    };
+} | {
+    type: "killTransport";
+    params: unknown;
+}, {
+    type: "abortRequested";
+    params: unknown;
+}, never, "idle" | "failed" | "aborted" | "initializing" | "uploading" | "completing" | "aborting" | "succeeded", string, NonReducibleUnknown, NonReducibleUnknown, EventObject, MetaObject, {
+    id: "uploader";
+    states: {
+        readonly idle: {};
+        readonly initializing: {};
+        readonly uploading: {};
+        readonly completing: {};
+        readonly aborting: {};
+        readonly succeeded: {};
+        readonly failed: {};
+        readonly aborted: {};
+    };
+}>;

package/dist/types/storage/uploader.d.ts

@@ -4,8 +4,14 @@ import { UploaderOptions, UploadProgress, UploadResult, UploadStatus } from './t
 /**
  * Drives a single file through the four-step chunked upload protocol
  * (`init_upload → upload_part* → complete_upload`) exposed by the framework's
- * `sys/storage` resource. Errors trigger a best-effort `abort_upload` so the
- * backend never retains a dangling multipart session.
+ * `sys/storage` resource. A caller abort triggers a best-effort
+ * `abort_upload`; non-abort failures leave the session intact so the upload
+ * can resume.
+ *
+ * The lifecycle is governed by the statechart in `./uploader-machine.ts`:
+ * this class supplies the phase runners (session prep, worker pool,
+ * completion, backend abort) and bridges actor snapshots onto the public
+ * `status` / `onStatusChange` / `start()`-promise surface.
  *
  * The instance is one-shot: a successful or failed run cannot be restarted.
  * Create a fresh `Uploader` for each file.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vef-framework-react/core",
   "type": "module",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "private": false,
   "description": "Core features for VEF framework",
   "author": {
@@ -56,20 +56,20 @@
     "@emotion/react": "^11.14.0",
     "@hello-pangea/dnd": "^18.0.1",
     "@microsoft/fetch-event-source": "^2.0.1",
-    "@tanstack/react-query": "^5.100.9",
+    "@tanstack/react-query": "^5.101.0",
     "@xstate/react": "^6.1.0",
-    "axios": "^1.16.0",
+    "axios": "^1.17.0",
     "clsx": "^2.1.1",
     "immer": "^11.1.7",
     "jotai": "^2.20.0",
-    "motion": "^12.38.0",
+    "motion": "^12.40.0",
     "use-immer": "^0.11.0",
-    "xstate": "^5.31.0",
-    "zustand": "^5.0.13",
-    "@vef-framework-react/shared": "2.3.0"
+    "xstate": "^5.32.0",
+    "zustand": "^5.0.14",
+    "@vef-framework-react/shared": "2.4.1"
   },
   "devDependencies": {
-    "react": "^19.2.6"
+    "react": "^19.2.7"
   },
   "scripts": {
     "clean": "rimraf dist",