nucleus-core-ts 0.9.975 → 0.9.976

package/dist/nucleus.config.d.ts

@@ -41,7 +41,7 @@ export declare const config: {
      * redefined globals the consuming app relies on — `setTimeout` started
      * reporting "expected 1 argument" in files that had never heard of us.
      */
-    readonly transpileDirs: readonly ["./src/Client/PubSub", "./src/Shared"];
+    readonly transpileDirs: readonly ["./src/Client/PubSub", "./src/Client/Upload", "./src/Shared"];
     /** Build Configuration */
     readonly build: {
         readonly outDir: "dist";

package/dist/src/Client/Upload/index.d.ts

@@ -0,0 +1,4 @@
+export { buildProgress, createRateWindow, type RateSample, type RateWindow, secondsRemaining, uploadFraction, uploadPercent, } from './progress';
+export type { UploadHandle, UploadOptions, UploadOutcome, UploadProgress, } from './types';
+export { uploadWithProgress } from './upload';
+export { type UseUploadResult, useUpload } from './useUpload';

package/dist/src/Client/Upload/index.js

@@ -0,0 +1,3 @@
+export { buildProgress, createRateWindow, secondsRemaining, uploadFraction, uploadPercent } from './progress';
+export { uploadWithProgress } from './upload';
+export { useUpload } from './useUpload';

package/dist/src/Client/Upload/progress.js

@@ -0,0 +1,102 @@
+/**
+ * How long is "how long is left".
+ *
+ * The naive answer — bytes remaining divided by the rate since the last report
+ * — is unusable on a real connection. Between two packets the instantaneous
+ * rate swings by an order of magnitude, so the countdown reads "8 saniye", then
+ * "4 dakika", then "11 saniye", and the person watching learns to ignore it.
+ *
+ * So the rate is measured across a window instead: the oldest sample still
+ * inside WINDOW_MS against the newest. Long enough that one slow packet cannot
+ * move it much, short enough that a connection genuinely getting slower is
+ * reflected within a couple of seconds rather than being averaged away by a
+ * fast start.
+ */ const WINDOW_MS = 5000;
+/**
+ * Below this, there is no answer worth giving.
+ *
+ * A rate computed from 80 ms of history is noise wearing a number, and the
+ * first estimate is the one people remember. Until the window has this much in
+ * it the remaining time is `null` and the screen shows a bar without a
+ * countdown — which is honest, and settles within a second on any real upload.
+ */ const MIN_SPAN_MS = 700;
+/**
+ * A short history of byte counts, from which a believable rate can be drawn.
+ *
+ * Deliberately a plain object with functions rather than a class: it has to be
+ * usable from a hook's ref, a plain script and a test, and it holds nothing
+ * that needs a lifecycle.
+ */ export function createRateWindow(windowMs = WINDOW_MS) {
+    const samples = [];
+    return {
+        /** Record a byte count. Out-of-order and duplicate times are tolerated. */ push (at, bytes) {
+            const last = samples[samples.length - 1];
+            // A report that did not advance the clock cannot inform a rate, but it
+            // can inform the byte count — so replace rather than append.
+            if (last && at <= last.at) {
+                last.bytes = Math.max(last.bytes, bytes);
+                return;
+            }
+            samples.push({
+                at,
+                bytes
+            });
+            const cutoff = at - windowMs;
+            while(samples.length > 2 && samples[0].at < cutoff){
+                samples.shift();
+            }
+        },
+        /** Bytes per second across the window, or `null` while it means nothing. */ ratePerSecond () {
+            if (samples.length < 2) return null;
+            const first = samples[0];
+            const last = samples[samples.length - 1];
+            const spanMs = last.at - first.at;
+            if (spanMs < MIN_SPAN_MS) return null;
+            const delta = last.bytes - first.bytes;
+            // A window in which nothing arrived is a stall, not a speed of zero: a
+            // zero would make the remaining time infinite, which is not an estimate.
+            if (delta <= 0) return null;
+            return delta * 1000 / spanMs;
+        },
+        reset () {
+            samples.length = 0;
+        }
+    };
+}
+/** 0..1, or `null` when the total is unknown. Clamped — a server that counts differently must not produce 103%. */ export function uploadFraction(sentBytes, totalBytes) {
+    if (totalBytes === null || totalBytes <= 0) return null;
+    return Math.min(1, Math.max(0, sentBytes / totalBytes));
+}
+/** 0..100 rounded, or `null`. Floored below 100 so a bar never reads "100%" while bytes are still moving. */ export function uploadPercent(sentBytes, totalBytes) {
+    const fraction = uploadFraction(sentBytes, totalBytes);
+    if (fraction === null) return null;
+    if (fraction >= 1) return 100;
+    return Math.min(99, Math.floor(fraction * 100));
+}
+/**
+ * Seconds left, or `null` when that cannot be said yet.
+ *
+ * Returns 0 — not null — once every byte is accounted for, because "done" is
+ * something we DO know and a screen should be able to close on it.
+ */ export function secondsRemaining(sentBytes, totalBytes, bytesPerSecond) {
+    if (totalBytes === null || totalBytes <= 0) return null;
+    const left = totalBytes - sentBytes;
+    if (left <= 0) return 0;
+    if (bytesPerSecond === null || bytesPerSecond <= 0) return null;
+    return left / bytesPerSecond;
+}
+/** Assembles one honest progress report from a byte count and a rate window. */ export function buildProgress(params) {
+    const { sentBytes, totalBytes, startedAt, now, window, retrying = false } = params;
+    window.push(now, sentBytes);
+    const bytesPerSecond = window.ratePerSecond();
+    return {
+        sentBytes,
+        totalBytes,
+        fraction: uploadFraction(sentBytes, totalBytes),
+        percent: uploadPercent(sentBytes, totalBytes),
+        bytesPerSecond,
+        secondsRemaining: secondsRemaining(sentBytes, totalBytes, bytesPerSecond),
+        elapsedMs: Math.max(0, now - startedAt),
+        retrying
+    };
+}

package/dist/src/Client/Upload/types.d.ts

@@ -74,4 +74,20 @@ export interface UploadOptions<TData> {
      * timer is how "sonsuz boyut" quietly becomes "as long as this number".
      */
     timeoutMs?: number;
+    /**
+     * Where the request object comes from. Defaults to the global
+     * `XMLHttpRequest`.
+     *
+     * This exists because the byte counting is a BROWSER guarantee and nothing
+     * else implements it. Bun has no `XMLHttpRequest` at all, and happy-dom's
+     * has an `upload` object that never fires a single progress event —
+     * measured: zero, on an 8 MB body. A test written against that would be a
+     * test that cannot fail, which is worse than no test.
+     *
+     * So the transport's own logic — when it reports, what it does with each
+     * outcome, that it never rejects — is exercised against a stand-in that
+     * emits the events a browser emits, and the byte counting itself is proven
+     * in a browser. Anything else would be proving the stand-in.
+     */
+    createRequest?: () => XMLHttpRequest;
 }

package/dist/src/Client/Upload/types.js

@@ -0,0 +1,8 @@
+/**
+ * What an upload can honestly say about itself while it is happening.
+ *
+ * Every field that can be unknown is `null` rather than 0 or a guess. That is
+ * the whole design: a bar drawn at 0% that never moves, or a countdown that
+ * says "3 seconds" for four minutes, is worse than saying nothing — the person
+ * stops believing the screen, and then they do not believe it when it is right.
+ */ export { };

package/dist/src/Client/Upload/upload.d.ts

@@ -0,0 +1,10 @@
+import type { UploadHandle, UploadOptions, UploadProgress } from './types';
+/**
+ * Posts a body and reports honest progress while it goes.
+ *
+ * Resolves either way and never rejects, because a caller that has to wrap
+ * every upload in try/catch ends up with one that does not, and then a failed
+ * upload looks like a successful one.
+ */
+export declare function uploadWithProgress<TData = unknown>(body: FormData | Blob | ArrayBufferView | ArrayBuffer | string, options: UploadOptions<TData>): UploadHandle<TData>;
+export type { UploadProgress };

package/dist/src/Client/Upload/upload.js

@@ -0,0 +1,156 @@
+import { buildProgress, createRateWindow } from './progress';
+/**
+ * An upload the browser can actually count.
+ *
+ * `XMLHttpRequest` and not `fetch`, and the reason is not preference: fetch
+ * reports NO upload progress at all. A request body stream would need
+ * `duplex: 'half'`, which is not supported across the browsers this has to run
+ * on, and even then it reports what the stream produced, not what the socket
+ * accepted. `xhr.upload.onprogress` is the only mechanism a browser gives that
+ * counts bytes handed to the network.
+ *
+ * It is also the reason a framework server action cannot be used here. A server
+ * action is a request the framework owns; it exposes nothing about its
+ * progress, it cannot be aborted, and it buffers the whole body in the web
+ * process before a byte reaches storage. Measured on a live install: a large
+ * video appeared to upload and then simply did not arrive.
+ */ /** How often to report, at most. Every progress event would re-render for nothing. */ const MIN_REPORT_INTERVAL_MS = 120;
+/**
+ * Posts a body and reports honest progress while it goes.
+ *
+ * Resolves either way and never rejects, because a caller that has to wrap
+ * every upload in try/catch ends up with one that does not, and then a failed
+ * upload looks like a successful one.
+ */ export function uploadWithProgress(body, options) {
+    const xhr = options.createRequest ? options.createRequest() : new XMLHttpRequest();
+    const window = createRateWindow();
+    const startedAt = Date.now();
+    let lastReportAt = 0;
+    let settled = false;
+    /** The last totals the browser reported, so completion can be stated exactly. */ let lastSent = 0;
+    let lastTotal = null;
+    const report = (sentBytes, totalBytes, force)=>{
+        if (!options.onProgress) return;
+        const now = Date.now();
+        if (!force && now - lastReportAt < MIN_REPORT_INTERVAL_MS) return;
+        lastReportAt = now;
+        options.onProgress(buildProgress({
+            sentBytes,
+            totalBytes,
+            startedAt,
+            now,
+            window
+        }));
+    };
+    const done = new Promise((resolve)=>{
+        const settle = (outcome)=>{
+            if (settled) return;
+            settled = true;
+            resolve(outcome);
+        };
+        xhr.open('POST', options.url, true);
+        // The session cookie is what authenticates an upload; the proxy in front
+        // turns it into whatever bearer the API wants.
+        xhr.withCredentials = options.withCredentials !== false;
+        for (const [key, value] of Object.entries(options.headers ?? {})){
+            xhr.setRequestHeader(key, value);
+        }
+        // Deliberately unset by default. An upload bounded by disk rather than
+        // memory can legitimately run for a very long time, and a timer is how
+        // "no size limit" quietly becomes "as long as this number".
+        if (options.timeoutMs) xhr.timeout = options.timeoutMs;
+        xhr.upload.onprogress = (event)=>{
+            lastSent = event.loaded;
+            // `lengthComputable` false means the browser will not total this body.
+            // Saying `null` is the whole design — see UploadProgress.
+            lastTotal = event.lengthComputable ? event.total : null;
+            report(lastSent, lastTotal, false);
+        };
+        xhr.upload.onload = ()=>{
+            // Every byte is on the socket now. The server has not answered yet, but
+            // the part this can measure IS finished, and a bar frozen at 99% while a
+            // large file is committed reads as a hang. Reported from the browser's
+            // own last numbers rather than a guess about what "all of it" means.
+            report(lastTotal ?? lastSent, lastTotal, true);
+        };
+        xhr.onload = ()=>{
+            let parsed = null;
+            try {
+                parsed = xhr.responseText ? JSON.parse(xhr.responseText) : null;
+            } catch  {
+                parsed = null;
+            }
+            if (xhr.status < 200 || xhr.status >= 300) {
+                settle({
+                    ok: false,
+                    status: xhr.status,
+                    message: serverMessage(parsed) || xhr.statusText || '',
+                    cancelled: false
+                });
+                return;
+            }
+            const data = options.parse ? options.parse(parsed) : parsed;
+            if (data === null || data === undefined) {
+                // A 2xx whose body the caller does not recognise is not a success. An
+                // endpoint with its own envelope stays the caller's business.
+                settle({
+                    ok: false,
+                    status: xhr.status,
+                    message: serverMessage(parsed) || 'The server accepted the upload but returned nothing usable',
+                    cancelled: false
+                });
+                return;
+            }
+            settle({
+                ok: true,
+                data
+            });
+        };
+        xhr.onerror = ()=>{
+            settle({
+                ok: false,
+                status: null,
+                message: 'The upload could not reach the server',
+                cancelled: false
+            });
+        };
+        xhr.ontimeout = ()=>{
+            settle({
+                ok: false,
+                status: null,
+                message: 'The upload timed out',
+                cancelled: false
+            });
+        };
+        xhr.onabort = ()=>{
+            // Cancelled is carried separately so a screen can stay quiet about it.
+            // Somebody who pressed cancel does not need to be told it failed.
+            settle({
+                ok: false,
+                status: null,
+                message: '',
+                cancelled: true
+            });
+        };
+        xhr.send(body);
+    });
+    return {
+        done,
+        abort: ()=>{
+            xhr.abort();
+        }
+    };
+}
+/** Digs the server's own sentence out of whatever envelope it used. */ function serverMessage(parsed) {
+    if (!parsed || typeof parsed !== 'object') return '';
+    const body = parsed;
+    for (const key of [
+        'message',
+        'error',
+        'detail'
+    ]){
+        const value = body[key];
+        if (typeof value === 'string' && value) return value;
+    }
+    return '';
+}

package/dist/src/Client/Upload/useUpload.d.ts

@@ -0,0 +1,31 @@
+import type { UploadOptions, UploadOutcome, UploadProgress } from './types';
+/**
+ * One file at a time, with something honest to draw while it goes.
+ *
+ * The state is deliberately the progress object itself rather than a spread of
+ * separate numbers: a screen that reads `percent` and `secondsRemaining` from
+ * two different pieces of state can render a moment where they disagree, and
+ * the disagreement is what a person notices.
+ *
+ * `null` progress means nothing is in flight. That is a different statement
+ * from 0%, and the difference is what lets a screen show nothing at all rather
+ * than an empty bar sitting at zero.
+ */
+export interface UseUploadResult<TData> {
+    /** Live progress, or `null` when nothing is uploading. */
+    progress: UploadProgress | null;
+    /** True from the moment `start` is called until the outcome is known. */
+    uploading: boolean;
+    /** The last outcome, or `null` before the first attempt. */
+    outcome: UploadOutcome<TData> | null;
+    /**
+     * Begins an upload, cancelling any earlier one first. Resolves with the
+     * outcome, so a caller can `await` it without watching state.
+     */
+    start: (body: FormData | Blob | ArrayBufferView | ArrayBuffer | string, overrides?: Partial<UploadOptions<TData>>) => Promise<UploadOutcome<TData>>;
+    /** Stops the transfer for real. */
+    cancel: () => void;
+    /** Clears the last outcome and progress, e.g. when the form is reopened. */
+    reset: () => void;
+}
+export declare function useUpload<TData = unknown>(options: UploadOptions<TData>): UseUploadResult<TData>;

package/dist/src/Client/Upload/useUpload.js

@@ -0,0 +1,58 @@
+'use client';
+import { useCallback, useRef, useState } from 'react';
+import { uploadWithProgress } from './upload';
+export function useUpload(options) {
+    const [progress, setProgress] = useState(null);
+    const [uploading, setUploading] = useState(false);
+    const [outcome, setOutcome] = useState(null);
+    const handleRef = useRef(null);
+    // Read inside a callback that outlives the render it was created in, so the
+    // latest options are used rather than the ones captured at mount.
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    // Guards a slow upload from writing state after a newer one started, which
+    // is how a finished upload gets overwritten by a cancelled one's outcome.
+    const runId = useRef(0);
+    const cancel = useCallback(()=>{
+        handleRef.current?.abort();
+        handleRef.current = null;
+    }, []);
+    const reset = useCallback(()=>{
+        setProgress(null);
+        setOutcome(null);
+    }, []);
+    const start = useCallback(async (body, overrides)=>{
+        handleRef.current?.abort();
+        const id = ++runId.current;
+        setUploading(true);
+        setOutcome(null);
+        setProgress(null);
+        const merged = {
+            ...optionsRef.current,
+            ...overrides
+        };
+        const handle = uploadWithProgress(body, {
+            ...merged,
+            onProgress: (p)=>{
+                if (id !== runId.current) return;
+                setProgress(p);
+                merged.onProgress?.(p);
+            }
+        });
+        handleRef.current = handle;
+        const result = await handle.done;
+        if (id !== runId.current) return result;
+        handleRef.current = null;
+        setUploading(false);
+        setOutcome(result);
+        return result;
+    }, []);
+    return {
+        progress,
+        uploading,
+        outcome,
+        start,
+        cancel,
+        reset
+    };
+}

package/dist/src/Client/index.d.ts

@@ -2,3 +2,4 @@ export * from './ApiCaller';
 export * from './PubSub';
 export { ServerFetch, serverFetch } from './ServerFetch';
 export type { BaseError, HttpMethod, ServerFetchConfig, ServerFetchOptions, ServerFetchResponse, } from './ServerFetch/types';
+export * from './Upload';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nucleus-core-ts",
-	"version": "0.9.975",
+	"version": "0.9.976",
 	"description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
 	"author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
 	"license": "SEE LICENSE IN LICENSE",
@@ -77,6 +77,7 @@
 		"@types/bun": "latest",
 		"@types/pg": "latest",
 		"@types/react": "latest",
+		"@happy-dom/global-registrator": "^20.11.2",
 		"@types/react-dom": "latest",
 		"bun-plugin-tailwind": "latest",
 		"drizzle-kit": "latest",