nucleus-core-ts 0.9.992 → 0.9.993

package/dist/src/Client/PubSub/waitForReturn.js

@@ -1,38 +1,38 @@
-/**
- * Wait for the world to change, instead of retrying against a clock.
- *
- * A connection that has exhausted its attempts used to be dead until the person
- * reloaded the page: ten tries with backoff is roughly three minutes, so a shut
- * laptop, a lunch break or a slow deploy left realtime off for good while the
- * page still looked alive.
- *
- * Retrying forever is not the answer either — that is precisely what produced a
- * live install's reconnect storm. So this waits on events that mean something,
- * and adds ONE slow backstop for the case the events cannot cover: a tab that
- * is visible the whole time, on a machine that never went offline, while the
- * API takes longer to come back than ten attempts allow. That tab receives no
- * `visibilitychange` and no `online` — it would simply sit there dead for the
- * rest of the day, which is the exact complaint this is meant to end. A single
- * timer that fires minutes apart is not a storm; it is a floor.
- */ /**
- * How long a tab that nobody touches waits before trying again on its own.
- *
- * Long enough that a hundred idle tabs cost the server nothing worth measuring;
- * short enough that somebody who looks up from their work finds a live screen
- * rather than a dead one.
+/**
+ * Wait for the world to change, instead of retrying against a clock.
+ *
+ * A connection that has exhausted its attempts used to be dead until the person
+ * reloaded the page: ten tries with backoff is roughly three minutes, so a shut
+ * laptop, a lunch break or a slow deploy left realtime off for good while the
+ * page still looked alive.
+ *
+ * Retrying forever is not the answer either — that is precisely what produced a
+ * live install's reconnect storm. So this waits on events that mean something,
+ * and adds ONE slow backstop for the case the events cannot cover: a tab that
+ * is visible the whole time, on a machine that never went offline, while the
+ * API takes longer to come back than ten attempts allow. That tab receives no
+ * `visibilitychange` and no `online` — it would simply sit there dead for the
+ * rest of the day, which is the exact complaint this is meant to end. A single
+ * timer that fires minutes apart is not a storm; it is a floor.
+ */ /**
+ * How long a tab that nobody touches waits before trying again on its own.
+ *
+ * Long enough that a hundred idle tabs cost the server nothing worth measuring;
+ * short enough that somebody who looks up from their work finds a live screen
+ * rather than a dead one.
  */ export const BACKSTOP_MS = 2 * 60 * 1000;
-/**
- * The events worth waking for. `focus` and `pageshow` are here because
- * `visibilitychange` does not fire for a window that was merely behind another
- * one, or for a page restored from the back/forward cache.
+/**
+ * The events worth waking for. `focus` and `pageshow` are here because
+ * `visibilitychange` does not fire for a window that was merely behind another
+ * one, or for a page restored from the back/forward cache.
  */ const WINDOW_EVENTS = [
     'online',
     'focus',
     'pageshow'
 ];
-/**
- * Calls `onReturn` the first time the machine is both online and looked at, or
- * after the backstop if neither ever happens. Returns a disarm function.
+/**
+ * Calls `onReturn` the first time the machine is both online and looked at, or
+ * after the backstop if neither ever happens. Returns a disarm function.
  */ export function armReturnListeners(env, onReturn) {
     let fired = false;
     let timer = null;

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

@@ -1,31 +1,31 @@
-/**
- * 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.
+/**
+ * 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.
+/**
+ * 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.
+/**
+ * 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 {
@@ -73,11 +73,11 @@
     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.
+/**
+ * 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;

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

@@ -1,8 +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.
+/**
+ * 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.js

@@ -1,26 +1,26 @@
 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.
+/**
+ * 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.
+/**
+ * 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();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nucleus-core-ts",
-	"version": "0.9.992",
+	"version": "0.9.993",
 	"description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
 	"author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
 	"license": "SEE LICENSE IN LICENSE",