@flighthq/net 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './net';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './net';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC"}

package/dist/net.d.ts

@@ -0,0 +1,6 @@
+import type { NetBackend, NetRequest, NetRequestOptions, NetResponse } from '@flighthq/types';
+export declare function createWebNetBackend(): NetBackend;
+export declare function getNetBackend(): NetBackend;
+export declare function sendNetRequest(request: Readonly<NetRequest>, options?: Readonly<NetRequestOptions>): Promise<NetResponse>;
+export declare function setNetBackend(backend: NetBackend | null): void;
+//# sourceMappingURL=net.d.ts.map

package/dist/net.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net.d.ts","sourceRoot":"","sources":["../src/net.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,UAAU,EAEV,UAAU,EACV,iBAAiB,EACjB,WAAW,EAIZ,MAAM,iBAAiB,CAAC;AAQzB,wBAAgB,mBAAmB,IAAI,UAAU,CAwBhD;AAGD,wBAAgB,aAAa,IAAI,UAAU,CAG1C;AAKD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,EAC7B,OAAO,CAAC,EAAE,QAAQ,CAAC,iBAAiB,CAAC,GACpC,OAAO,CAAC,WAAW,CAAC,CAEtB;AAGD,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI,CAE9D"}

package/dist/net.js

@@ -0,0 +1,196 @@
+import { emitSignal } from '@flighthq/signals';
+// Builds the default web backend over fetch + AbortController. Created lazily by getNetBackend — no
+// fetch binding happens at import time, so importing the package has no side effect. Expected
+// transport failures (network error, DNS, timeout, caller abort) resolve to a sentinel NetResponse
+// (status 0, ok false) rather than rejecting; a non-2xx HTTP response is a normal NetResponse with
+// its real status and ok false. Only genuine misuse (a request no correct caller could produce)
+// surfaces as a thrown error from fetch itself.
+export function createWebNetBackend() {
+    return {
+        async sendNetRequest(request, options) {
+            const controller = new AbortController();
+            const teardownAbort = _wireNetAbort(controller, request.timeoutMs, options?.signal);
+            try {
+                const response = await fetch(request.url, _toNetFetchInit(request, controller.signal));
+                const headers = _readNetResponseHeaders(response.headers);
+                const body = await _readNetResponseBody(response, request.responseType ?? 'text', options?.progress);
+                return {
+                    status: response.status,
+                    statusText: response.statusText,
+                    ok: response.ok,
+                    headers,
+                    body,
+                    url: response.url !== '' ? response.url : request.url,
+                };
+            }
+            catch (error) {
+                return _netTransportFailure(request.url, controller.signal, error);
+            }
+            finally {
+                teardownAbort();
+            }
+        },
+    };
+}
+// The active net backend, lazily defaulting to the web fetch backend. There is always a backend.
+export function getNetBackend() {
+    if (_backend === null)
+        _backend = createWebNetBackend();
+    return _backend;
+}
+// Issues one HTTP(S) request through the active backend and resolves to a plain-data NetResponse.
+// Expected transport failures resolve as a sentinel response (status 0, ok false); a non-2xx status
+// is a normal response with ok false. Progress and cancellation come from options.
+export function sendNetRequest(request, options) {
+    return getNetBackend().sendNetRequest(request, options);
+}
+// Installs a native host transport backend; pass null to fall back to the lazy web default.
+export function setNetBackend(backend) {
+    _backend = backend;
+}
+let _backend = null;
+// A sentinel abort reason so a timeout-triggered abort is distinguishable from a caller abort.
+const _netTimeoutReason = { flightNetTimeout: true };
+// Reads the numeric Content-Length, or -1 when it is absent or unparseable.
+function _netContentLength(headers) {
+    const raw = headers.get('content-length');
+    if (raw === null)
+        return -1;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : -1;
+}
+// Maps a fetch failure onto a sentinel NetResponse. A timeout and a caller abort are distinguished by
+// the controller's abort reason; any other rejection is reported as a network error.
+function _netTransportFailure(url, signal, error) {
+    let statusText = 'network error';
+    if (signal.aborted) {
+        statusText = signal.reason === _netTimeoutReason ? 'timeout' : 'aborted';
+    }
+    else if (error instanceof Error && error.message !== '') {
+        statusText = error.message;
+    }
+    return { status: 0, statusText, ok: false, headers: {}, body: null, url };
+}
+// Decodes an assembled byte buffer per the response type. JSON parse failure resolves to null rather
+// than throwing — a malformed JSON body is an expected-failure surface, not programmer error.
+function _decodeNetBuffer(buffer, responseType) {
+    if (responseType === 'arraybuffer')
+        return buffer;
+    if (responseType === 'blob')
+        return new Blob([buffer]);
+    const text = new TextDecoder().decode(buffer);
+    if (responseType === 'json') {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    return text;
+}
+// Reads the whole response body, decoding it per responseType. When a progress signal is supplied the
+// download stream is drained chunk-by-chunk so progress ticks can be emitted; otherwise the native
+// per-type reader is used directly.
+async function _readNetResponseBody(response, responseType, progress) {
+    if (progress !== undefined) {
+        const buffer = await _readNetResponseWithProgress(response, progress);
+        return _decodeNetBuffer(buffer, responseType);
+    }
+    if (responseType === 'arraybuffer')
+        return await response.arrayBuffer();
+    if (responseType === 'blob')
+        return await response.blob();
+    if (responseType === 'json') {
+        try {
+            return (await response.json());
+        }
+        catch {
+            return null;
+        }
+    }
+    return await response.text();
+}
+// Collects the response body as bytes while emitting download progress ticks. Falls back to a single
+// whole-body read (with one terminal tick) when the response exposes no readable stream.
+async function _readNetResponseWithProgress(response, progress) {
+    const total = _netContentLength(response.headers);
+    const stream = response.body;
+    if (stream === null || typeof stream.getReader !== 'function') {
+        const buffer = await response.arrayBuffer();
+        emitSignal(progress, {
+            phase: 'download',
+            loaded: buffer.byteLength,
+            total: total >= 0 ? total : buffer.byteLength,
+        });
+        return buffer;
+    }
+    const reader = stream.getReader();
+    const chunks = [];
+    let loaded = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value === undefined)
+            continue;
+        chunks.push(value);
+        loaded += value.byteLength;
+        emitSignal(progress, { phase: 'download', loaded, total: total >= 0 ? total : 0 });
+    }
+    const out = new Uint8Array(loaded);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out.buffer;
+}
+// Copies the response's headers into a plain, case-insensitive-keyed record.
+function _readNetResponseHeaders(headers) {
+    const out = {};
+    headers.forEach((value, key) => {
+        out[key] = value;
+    });
+    return out;
+}
+// Maps a NetRequest onto a fetch RequestInit, wiring the merged abort signal. A null/absent body is
+// left off entirely so bodyless methods (GET/HEAD) are valid.
+function _toNetFetchInit(request, signal) {
+    const init = { method: request.method, signal };
+    if (request.headers !== undefined)
+        init.headers = { ...request.headers };
+    if (request.body !== undefined && request.body !== null)
+        init.body = request.body;
+    if (request.credentials !== undefined)
+        init.credentials = request.credentials;
+    if (request.redirect !== undefined)
+        init.redirect = request.redirect;
+    return init;
+}
+// Wires the request timeout and the caller's abort signal into one controller. Returns a teardown
+// that clears the timer and detaches the caller listener. A timeout aborts with a sentinel reason so
+// the failure path can label it 'timeout' rather than 'aborted'.
+function _wireNetAbort(controller, timeoutMs, signal) {
+    let timer = null;
+    if (typeof timeoutMs === 'number' && timeoutMs >= 0) {
+        timer = setTimeout(() => controller.abort(_netTimeoutReason), timeoutMs);
+    }
+    let onAbort = null;
+    if (signal !== undefined) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+        }
+        else {
+            onAbort = () => controller.abort(signal.reason);
+            signal.addEventListener('abort', onAbort);
+        }
+    }
+    return () => {
+        if (timer !== null)
+            clearTimeout(timer);
+        if (onAbort !== null && signal !== undefined)
+            signal.removeEventListener('abort', onAbort);
+    };
+}
+//# sourceMappingURL=net.js.map

package/dist/net.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"net.js","sourceRoot":"","sources":["../src/net.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/net",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/signals": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "HTTP(S) transport (URLLoader/URLRequest) over a swappable web/native backend (fetch by default)",
+  "sideEffects": false
+}

package/src/net.test.ts

@@ -0,0 +1,265 @@
+import { createSignal } from '@flighthq/signals';
+import type { NetBackend, NetProgress, NetRequest, NetResponse } from '@flighthq/types';
+
+import { createWebNetBackend, getNetBackend, sendNetRequest, setNetBackend } from './net';
+
+interface FakeResponseInit {
+  status?: number;
+  statusText?: string;
+  headers?: Record<string, string>;
+  url?: string;
+  text?: string;
+  json?: unknown;
+  arraybuffer?: ArrayBuffer;
+  blob?: Blob;
+  streamChunks?: Uint8Array[];
+}
+
+function fakeResponse(init: FakeResponseInit): Response {
+  const status = init.status ?? 200;
+  const headerMap = new Map<string, string>(Object.entries(init.headers ?? {}).map(([k, v]) => [k.toLowerCase(), v]));
+  const headers = {
+    get: (name: string) => headerMap.get(name.toLowerCase()) ?? null,
+    forEach: (cb: (value: string, key: string) => void) => headerMap.forEach((v, k) => cb(v, k)),
+  };
+  const body =
+    init.streamChunks !== undefined ? { getReader: () => makeReader(init.streamChunks as Uint8Array[]) } : null;
+  return {
+    status,
+    statusText: init.statusText ?? '',
+    ok: status >= 200 && status < 300,
+    url: init.url ?? '',
+    headers,
+    body,
+    text: async () => init.text ?? '',
+    json: async () => {
+      if (init.json === undefined) throw new SyntaxError('no json');
+      return init.json;
+    },
+    arrayBuffer: async () => init.arraybuffer ?? new ArrayBuffer(0),
+    blob: async () => init.blob ?? new Blob([]),
+  } as unknown as Response;
+}
+
+function makeReader(chunks: readonly Uint8Array[]): { read: () => Promise<{ done: boolean; value?: Uint8Array }> } {
+  let i = 0;
+  return {
+    read: async () => {
+      if (i < chunks.length) {
+        const value = chunks[i];
+        i += 1;
+        return { done: false, value };
+      }
+      return { done: true, value: undefined };
+    },
+  };
+}
+
+let originalFetch: typeof fetch | undefined;
+
+beforeEach(() => {
+  originalFetch = globalThis.fetch;
+});
+
+afterEach(() => {
+  if (originalFetch !== undefined) globalThis.fetch = originalFetch;
+  setNetBackend(null);
+});
+
+describe('createWebNetBackend', () => {
+  it('maps method, headers, and body onto the fetch init', async () => {
+    let captured: { url?: string; init?: RequestInit } = {};
+    globalThis.fetch = (async (url: string, init: RequestInit) => {
+      captured = { url, init };
+      return fakeResponse({ status: 200, text: 'ok' });
+    }) as unknown as typeof fetch;
+    const backend = createWebNetBackend();
+    const request: NetRequest = {
+      method: 'POST',
+      url: 'https://example.test/api',
+      headers: { 'X-Token': 'abc' },
+      body: 'payload',
+    };
+    await backend.sendNetRequest(request);
+    expect(captured.url).toBe('https://example.test/api');
+    expect(captured.init?.method).toBe('POST');
+    expect(captured.init?.headers).toEqual({ 'X-Token': 'abc' });
+    expect(captured.init?.body).toBe('payload');
+    expect(captured.init?.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it('omits the body for a bodyless request', async () => {
+    let init: RequestInit | undefined;
+    globalThis.fetch = (async (_url: string, i: RequestInit) => {
+      init = i;
+      return fakeResponse({ status: 200, text: '' });
+    }) as unknown as typeof fetch;
+    await createWebNetBackend().sendNetRequest({ method: 'GET', url: 'https://example.test' });
+    expect(init?.body).toBeUndefined();
+  });
+
+  it('decodes a text response', async () => {
+    globalThis.fetch = (async () => fakeResponse({ text: 'hello' })) as unknown as typeof fetch;
+    const res = await createWebNetBackend().sendNetRequest({ method: 'GET', url: 'u', responseType: 'text' });
+    expect(res.body).toBe('hello');
+    expect(res.ok).toBe(true);
+  });
+
+  it('decodes a json response', async () => {
+    globalThis.fetch = (async () => fakeResponse({ json: { x: 1 } })) as unknown as typeof fetch;
+    const res = await createWebNetBackend().sendNetRequest({ method: 'GET', url: 'u', responseType: 'json' });
+    expect(res.body).toEqual({ x: 1 });
+  });
+
+  it('returns null for a malformed json body without throwing', async () => {
+    globalThis.fetch = (async () => fakeResponse({ status: 200 })) as unknown as typeof fetch;
+    const res = await createWebNetBackend().sendNetRequest({ method: 'GET', url: 'u', responseType: 'json' });
+    expect(res.body).toBeNull();
+    expect(res.ok).toBe(true);
+  });
+
+  it('decodes an arraybuffer response', async () => {
+    const buffer = new Uint8Array([1, 2, 3]).buffer;
+    globalThis.fetch = (async () => fakeResponse({ arraybuffer: buffer })) as unknown as typeof fetch;
+    const res = await createWebNetBackend().sendNetRequest({ method: 'GET', url: 'u', responseType: 'arraybuffer' });
+    expect(res.body).toBe(buffer);
+  });
+
+  it('decodes a blob response', async () => {
+    const blob = new Blob(['x']);
+    globalThis.fetch = (async () => fakeResponse({ blob })) as unknown as typeof fetch;
+    const res = await createWebNetBackend().sendNetRequest({ method: 'GET', url: 'u', responseType: 'blob' });
+    expect(res.body).toBe(blob);
+  });
+
+  it('surfaces a non-2xx response as ok:false with the real status, not a throw', async () => {
+    globalThis.fetch = (async () =>
+      fakeResponse({ status: 404, statusText: 'Not Found', text: 'nope' })) as unknown as typeof fetch;
+    const res = await createWebNetBackend().sendNetRequest({ method: 'GET', url: 'u' });
+    expect(res.status).toBe(404);
+    expect(res.ok).toBe(false);
+    expect(res.statusText).toBe('Not Found');
+    expect(res.body).toBe('nope');
+  });
+
+  it('resolves a thrown fetch (network error) to a sentinel response', async () => {
+    globalThis.fetch = (async () => {
+      throw new TypeError('Failed to fetch');
+    }) as unknown as typeof fetch;
+    const res = await createWebNetBackend().sendNetRequest({ method: 'GET', url: 'u' });
+    expect(res.status).toBe(0);
+    expect(res.ok).toBe(false);
+    expect(res.statusText).toBe('Failed to fetch');
+    expect(res.body).toBeNull();
+  });
+
+  it('resolves a timeout to an aborted sentinel labeled timeout', async () => {
+    globalThis.fetch = ((_url: string, init: RequestInit) =>
+      new Promise<Response>((_resolve, reject) => {
+        const signal = init.signal as AbortSignal;
+        if (signal.aborted) {
+          reject(new DOMException('aborted', 'AbortError'));
+          return;
+        }
+        signal.addEventListener('abort', () => reject(new DOMException('aborted', 'AbortError')));
+      })) as unknown as typeof fetch;
+    const res = await createWebNetBackend().sendNetRequest({ method: 'GET', url: 'u', timeoutMs: 5 });
+    expect(res.status).toBe(0);
+    expect(res.ok).toBe(false);
+    expect(res.statusText).toBe('timeout');
+  });
+
+  it('resolves a caller abort to an aborted sentinel', async () => {
+    globalThis.fetch = ((_url: string, init: RequestInit) =>
+      new Promise<Response>((_resolve, reject) => {
+        const signal = init.signal as AbortSignal;
+        signal.addEventListener('abort', () => reject(new DOMException('aborted', 'AbortError')));
+      })) as unknown as typeof fetch;
+    const controller = new AbortController();
+    const promise = createWebNetBackend().sendNetRequest({ method: 'GET', url: 'u' }, { signal: controller.signal });
+    controller.abort();
+    const res = await promise;
+    expect(res.status).toBe(0);
+    expect(res.statusText).toBe('aborted');
+  });
+
+  it('emits download progress ticks when a progress signal is supplied', async () => {
+    globalThis.fetch = (async () =>
+      fakeResponse({
+        headers: { 'content-length': '5' },
+        streamChunks: [new Uint8Array([104, 105]), new Uint8Array([33, 33, 33])],
+      })) as unknown as typeof fetch;
+    const progress = createSignal<(progress: Readonly<NetProgress>) => void>();
+    const ticks: NetProgress[] = [];
+    progress.emit = (tick) => ticks.push({ ...tick });
+    const res = await createWebNetBackend().sendNetRequest(
+      { method: 'GET', url: 'u', responseType: 'text' },
+      { progress },
+    );
+    expect(ticks).toHaveLength(2);
+    expect(ticks[0]).toEqual({ phase: 'download', loaded: 2, total: 5 });
+    expect(ticks[1]).toEqual({ phase: 'download', loaded: 5, total: 5 });
+    expect(res.body).toBe('hi!!!');
+  });
+
+  it('reads response headers into a plain record', async () => {
+    globalThis.fetch = (async () =>
+      fakeResponse({ headers: { 'content-type': 'text/plain' }, text: 'x' })) as unknown as typeof fetch;
+    const res = await createWebNetBackend().sendNetRequest({ method: 'GET', url: 'u' });
+    expect(res.headers['content-type']).toBe('text/plain');
+  });
+});
+
+describe('getNetBackend', () => {
+  it('lazily returns a web backend by default', () => {
+    expect(getNetBackend()).not.toBeNull();
+    expect(typeof getNetBackend().sendNetRequest).toBe('function');
+  });
+
+  it('returns the installed backend', () => {
+    const backend: NetBackend = { sendNetRequest: async () => stubResponse() };
+    setNetBackend(backend);
+    expect(getNetBackend()).toBe(backend);
+  });
+});
+
+describe('sendNetRequest', () => {
+  it('dispatches through the active backend and passes options', async () => {
+    let received: { request?: Readonly<NetRequest>; options?: unknown } = {};
+    const backend: NetBackend = {
+      sendNetRequest: async (request, options) => {
+        received = { request, options };
+        return stubResponse();
+      },
+    };
+    setNetBackend(backend);
+    const request: NetRequest = { method: 'GET', url: 'https://example.test' };
+    const options = {};
+    await sendNetRequest(request, options);
+    expect(received.request).toBe(request);
+    expect(received.options).toBe(options);
+  });
+
+  it('passes the response through unchanged', async () => {
+    const response = stubResponse();
+    setNetBackend({ sendNetRequest: async () => response });
+    const result = await sendNetRequest({ method: 'GET', url: 'u' });
+    expect(result).toBe(response);
+  });
+});
+
+describe('setNetBackend', () => {
+  it('restores the lazy web default when passed null', () => {
+    const backend: NetBackend = { sendNetRequest: async () => stubResponse() };
+    setNetBackend(backend);
+    expect(getNetBackend()).toBe(backend);
+    setNetBackend(null);
+    const web = getNetBackend();
+    expect(web).not.toBe(backend);
+    expect(typeof web.sendNetRequest).toBe('function');
+  });
+});
+
+function stubResponse(): NetResponse {
+  return { status: 200, statusText: 'OK', ok: true, headers: {}, body: null, url: 'u' };
+}