@lusor/sdk 0.0.0-stage → 1.0.0

package/dist/core/stream/Stream.js

@@ -0,0 +1,428 @@
+import { fromJson } from "../json.js";
+import { RUNTIME } from "../runtime/index.js";
+const DATA_PREFIX = "data:";
+const EVENT_PREFIX = "event:";
+const ID_PREFIX = "id:";
+const RETRY_PREFIX = "retry:";
+const DEFAULT_MAX_RECONNECTION_ATTEMPTS = 5;
+const DEFAULT_RECONNECT_DELAY_MS = 1_000;
+const MAX_RECONNECT_DELAY_MS = 30_000;
+export class Stream {
+    stream;
+    parse;
+    /**
+     * The prefix to use for each message. For example,
+     * for SSE, the prefix is "data: ".
+     */
+    prefix;
+    messageTerminator;
+    streamTerminator;
+    eventDiscriminator;
+    resumable;
+    reconnectionEnabled;
+    maxReconnectionAttempts;
+    reconnect;
+    controller = new AbortController();
+    decoder;
+    externalSignal;
+    onExternalAbort;
+    constructor({ stream, parse, eventShape, signal, reconnectionEnabled, maxReconnectionAttempts, reconnect, }) {
+        this.stream = stream;
+        this.parse = parse;
+        if (eventShape.type === "sse") {
+            this.prefix = DATA_PREFIX;
+            this.messageTerminator = "\n";
+            this.streamTerminator = eventShape.streamTerminator;
+            this.eventDiscriminator = eventShape.eventDiscriminator;
+            this.resumable = eventShape.resumable ?? false;
+        }
+        else {
+            this.messageTerminator = eventShape.messageTerminator;
+            this.resumable = false;
+        }
+        this.reconnectionEnabled = reconnectionEnabled ?? true;
+        this.maxReconnectionAttempts = maxReconnectionAttempts ?? DEFAULT_MAX_RECONNECTION_ATTEMPTS;
+        this.reconnect = reconnect;
+        if (signal != null) {
+            this.externalSignal = signal;
+            this.onExternalAbort = () => this.controller.abort();
+            signal.addEventListener("abort", this.onExternalAbort, { once: true });
+        }
+        // Initialize shared TextDecoder
+        if (typeof TextDecoder !== "undefined") {
+            this.decoder = new TextDecoder("utf-8");
+        }
+    }
+    async *iterMessages() {
+        if (this.eventDiscriminator != null) {
+            yield* this.iterSseEvents();
+        }
+        else {
+            yield* this.iterDataMessages();
+        }
+    }
+    async *iterDataMessages() {
+        let reconnectAttempts = 0;
+        let currentStream = this.stream;
+        let lastId;
+        // The id of the most recently *dispatched* event. Per the WHATWG
+        // EventSource spec, the "last event ID" is only committed when an event
+        // is dispatched, not when the `id:` line is parsed. Reconnecting with a
+        // parsed-but-undispatched id would skip an event that was never yielded
+        // (e.g. if the connection drops after `id:` but before the event's
+        // terminating blank line), so reconnection uses lastDispatchedId.
+        let lastDispatchedId;
+        let lastRetry;
+        while (true) {
+            const stream = readableStreamAsyncIterable(currentStream);
+            let buf = "";
+            let dataValue;
+            for await (const chunk of stream) {
+                buf += this.decodeChunk(chunk);
+                let terminatorIndex;
+                while ((terminatorIndex = buf.indexOf(this.messageTerminator)) >= 0) {
+                    const line = buf.slice(0, terminatorIndex);
+                    buf = buf.slice(terminatorIndex + this.messageTerminator.length);
+                    if (!line.trim()) {
+                        if (this.prefix != null && dataValue != null) {
+                            if (this.streamTerminator != null && dataValue.includes(this.streamTerminator)) {
+                                return;
+                            }
+                            const data = await this.parse(fromJson(dataValue));
+                            yield { data, id: lastId, retry: lastRetry, event: undefined };
+                            lastDispatchedId = lastId;
+                            reconnectAttempts = 0;
+                            dataValue = undefined;
+                        }
+                        continue;
+                    }
+                    if (line.startsWith(ID_PREFIX)) {
+                        const idValue = line.slice(ID_PREFIX.length).trim();
+                        if (!idValue.includes("\0")) {
+                            lastId = idValue;
+                        }
+                        continue;
+                    }
+                    if (line.startsWith(RETRY_PREFIX)) {
+                        const retryValue = line.slice(RETRY_PREFIX.length).trim();
+                        const parsed = parseInt(retryValue, 10);
+                        if (!Number.isNaN(parsed) && String(parsed) === retryValue) {
+                            lastRetry = parsed;
+                        }
+                        continue;
+                    }
+                    if (this.prefix != null) {
+                        const prefixIndex = line.indexOf(this.prefix);
+                        if (prefixIndex === -1) {
+                            continue;
+                        }
+                        const val = line.slice(prefixIndex + this.prefix.length).trim();
+                        dataValue = dataValue != null ? `${dataValue}\n${val}` : val;
+                    }
+                    else {
+                        if (this.streamTerminator != null && line.includes(this.streamTerminator)) {
+                            return;
+                        }
+                        const data = await this.parse(fromJson(line));
+                        yield { data, id: lastId, retry: lastRetry, event: undefined };
+                        lastDispatchedId = lastId;
+                        reconnectAttempts = 0;
+                    }
+                }
+            }
+            if (this.prefix != null && dataValue != null) {
+                if (this.streamTerminator != null && dataValue.includes(this.streamTerminator)) {
+                    return;
+                }
+                const data = await this.parse(fromJson(dataValue));
+                yield { data, id: lastId, retry: lastRetry, event: undefined };
+                lastDispatchedId = lastId;
+                reconnectAttempts = 0;
+            }
+            if (!this.shouldReconnect(lastDispatchedId, reconnectAttempts)) {
+                return;
+            }
+            reconnectAttempts++;
+            await this.delayReconnect(lastRetry);
+            if (this.controller.signal.aborted) {
+                return;
+            }
+            // Re-check after async delay; needed for TypeScript narrowing.
+            const reconnectFn = this.reconnect;
+            if (reconnectFn == null || lastDispatchedId == null) {
+                return;
+            }
+            try {
+                const reconnected = await reconnectFn(lastDispatchedId);
+                if (reconnected == null) {
+                    currentStream = this.createEmptyStream();
+                    continue;
+                }
+                currentStream = reconnected;
+            }
+            catch {
+                // Failed reconnect (e.g. HTTP error); assign an empty stream
+                // so the next iteration is a safe no-op before shouldReconnect.
+                currentStream = this.createEmptyStream();
+                continue;
+            }
+        }
+    }
+    async *iterSseEvents() {
+        let reconnectAttempts = 0;
+        let currentStream = this.stream;
+        let lastId;
+        // See iterDataMessages: reconnection uses the last *dispatched* id (per
+        // the EventSource spec), not the last *parsed* id, to avoid skipping an
+        // event that was never yielded when a drop lands mid-event.
+        let lastDispatchedId;
+        let lastRetry;
+        while (true) {
+            const stream = readableStreamAsyncIterable(currentStream);
+            let buf = "";
+            let eventType;
+            let dataValue;
+            for await (const chunk of stream) {
+                buf += this.decodeChunk(chunk);
+                let terminatorIndex;
+                while ((terminatorIndex = buf.indexOf("\n")) >= 0) {
+                    const line = buf.slice(0, terminatorIndex).replace(/\r$/, "");
+                    buf = buf.slice(terminatorIndex + 1);
+                    if (!line.trim()) {
+                        if (dataValue != null) {
+                            const data = await this.dispatchSseEvent(dataValue, eventType);
+                            if (data == null) {
+                                return;
+                            }
+                            yield { data, id: lastId, retry: lastRetry, event: eventType };
+                            lastDispatchedId = lastId;
+                            reconnectAttempts = 0;
+                        }
+                        eventType = undefined;
+                        dataValue = undefined;
+                        continue;
+                    }
+                    if (line.startsWith(EVENT_PREFIX)) {
+                        eventType = line.slice(EVENT_PREFIX.length).trim();
+                    }
+                    else if (line.startsWith(DATA_PREFIX)) {
+                        const val = line.slice(DATA_PREFIX.length).trim();
+                        dataValue = dataValue != null ? `${dataValue}\n${val}` : val;
+                    }
+                    else if (line.startsWith(ID_PREFIX)) {
+                        const idValue = line.slice(ID_PREFIX.length).trim();
+                        if (!idValue.includes("\0")) {
+                            lastId = idValue;
+                        }
+                    }
+                    else if (line.startsWith(RETRY_PREFIX)) {
+                        const retryValue = line.slice(RETRY_PREFIX.length).trim();
+                        const parsed = parseInt(retryValue, 10);
+                        if (!Number.isNaN(parsed) && String(parsed) === retryValue) {
+                            lastRetry = parsed;
+                        }
+                    }
+                }
+            }
+            if (dataValue != null) {
+                const data = await this.dispatchSseEvent(dataValue, eventType);
+                if (data != null) {
+                    yield { data, id: lastId, retry: lastRetry, event: eventType };
+                    lastDispatchedId = lastId;
+                    reconnectAttempts = 0;
+                }
+            }
+            if (!this.shouldReconnect(lastDispatchedId, reconnectAttempts)) {
+                return;
+            }
+            reconnectAttempts++;
+            await this.delayReconnect(lastRetry);
+            if (this.controller.signal.aborted) {
+                return;
+            }
+            // Re-check after async delay; needed for TypeScript narrowing.
+            const reconnectFn = this.reconnect;
+            if (reconnectFn == null || lastDispatchedId == null) {
+                return;
+            }
+            try {
+                const reconnected = await reconnectFn(lastDispatchedId);
+                if (reconnected == null) {
+                    currentStream = this.createEmptyStream();
+                    continue;
+                }
+                currentStream = reconnected;
+            }
+            catch {
+                // Failed reconnect (e.g. HTTP error); assign an empty stream
+                // so the next iteration is a safe no-op before shouldReconnect.
+                currentStream = this.createEmptyStream();
+                continue;
+            }
+        }
+    }
+    /**
+     * Parses and returns a single SSE event, or returns null if the event is a stream terminator.
+     */
+    async dispatchSseEvent(dataValue, eventType) {
+        if (this.streamTerminator != null && dataValue.includes(this.streamTerminator)) {
+            return null;
+        }
+        return this.parse(this.injectDiscriminator(fromJson(dataValue), eventType));
+    }
+    /**
+     * Determines whether a reconnection attempt should be made.
+     */
+    shouldReconnect(lastId, reconnectAttempts) {
+        if (!this.resumable) {
+            return false;
+        }
+        if (this.streamTerminator == null) {
+            // Without a terminator the client cannot distinguish a completed
+            // stream from a dropped connection, so reconnection is disabled.
+            return false;
+        }
+        // NOTE: When a terminator IS configured but the server never sends it
+        // (e.g. it drops the connection after emitting events every time),
+        // maxReconnectionAttempts is a per-consecutive-failure cap — each
+        // yielded event resets the counter. This matches EventSource semantics
+        // but means such a server can cause unbounded reconnections. Callers
+        // concerned about this should impose a wall-clock budget externally.
+        if (!this.reconnectionEnabled) {
+            return false;
+        }
+        if (this.reconnect == null) {
+            return false;
+        }
+        if (lastId == null || lastId === "") {
+            return false;
+        }
+        if (reconnectAttempts >= this.maxReconnectionAttempts) {
+            return false;
+        }
+        if (this.controller.signal.aborted) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Delays before reconnecting, using a server-sent retry directive if provided
+     * (clamped to MAX_RECONNECT_DELAY_MS), otherwise falling back to
+     * DEFAULT_RECONNECT_DELAY_MS. The delay is abortable: if the stream's abort
+     * signal fires during the wait, the promise resolves immediately.
+     */
+    async delayReconnect(lastRetry) {
+        const base = lastRetry != null && lastRetry > 0 ? lastRetry : DEFAULT_RECONNECT_DELAY_MS;
+        const delay = Math.min(base, MAX_RECONNECT_DELAY_MS);
+        const signal = this.controller.signal;
+        if (signal.aborted) {
+            return;
+        }
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                signal.removeEventListener("abort", onAbort);
+                resolve();
+            }, delay);
+            const onAbort = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    createEmptyStream() {
+        return new ReadableStream({
+            start(controller) {
+                controller.close();
+            },
+        });
+    }
+    removeAbortListener() {
+        if (this.externalSignal != null && this.onExternalAbort != null) {
+            this.externalSignal.removeEventListener("abort", this.onExternalAbort);
+            this.onExternalAbort = undefined;
+        }
+    }
+    withMetadata() {
+        const self = this;
+        return {
+            async *[Symbol.asyncIterator]() {
+                try {
+                    yield* self.iterMessages();
+                }
+                finally {
+                    self.removeAbortListener();
+                }
+            },
+        };
+    }
+    injectDiscriminator(parsed, eventType) {
+        if (this.eventDiscriminator == null || eventType == null) {
+            return parsed;
+        }
+        if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return parsed;
+        }
+        const obj = parsed;
+        if (this.eventDiscriminator in obj) {
+            return parsed;
+        }
+        return { [this.eventDiscriminator]: eventType, ...obj };
+    }
+    async *[Symbol.asyncIterator]() {
+        try {
+            for await (const event of this.iterMessages()) {
+                yield event.data;
+            }
+        }
+        finally {
+            this.removeAbortListener();
+        }
+    }
+    decodeChunk(chunk) {
+        let decoded = "";
+        // If TextDecoder is available, use the streaming decoder instance
+        if (this.decoder != null) {
+            decoded += this.decoder.decode(chunk, { stream: true });
+        }
+        // Buffer is present in Node.js environment
+        else if (RUNTIME.type === "node" && typeof chunk !== "undefined") {
+            decoded += Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        }
+        return decoded;
+    }
+}
+/**
+ * Browser polyfill for ReadableStream
+ */
+// biome-ignore lint/suspicious/noExplicitAny: allow explicit any
+export function readableStreamAsyncIterable(stream) {
+    if (stream[Symbol.asyncIterator]) {
+        return stream;
+    }
+    const reader = stream.getReader();
+    return {
+        async next() {
+            try {
+                const result = await reader.read();
+                if (result?.done) {
+                    reader.releaseLock();
+                } // release lock when stream becomes closed
+                return result;
+            }
+            catch (e) {
+                reader.releaseLock(); // release lock when stream becomes errored
+                throw e;
+            }
+        },
+        async return() {
+            const cancelPromise = reader.cancel();
+            reader.releaseLock();
+            await cancelPromise;
+            return { done: true, value: undefined };
+        },
+        [Symbol.asyncIterator]() {
+            return this;
+        },
+    };
+}

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

@@ -0,0 +1,2 @@
+export { Stream } from "./Stream.js";
+export type { ServerSentEvent } from "./Stream.js";

package/dist/core/stream/index.js

@@ -0,0 +1 @@
+export { Stream } from "./Stream.js";

package/dist/core/url/QueryStringBuilder.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Creates a fluent builder for constructing URL query strings.
+ *
+ * Each `.add()` call serializes its value immediately (like C#'s builder),
+ * so no format tracking is needed — the style is applied at add-time.
+ *
+ * Usage (generated code):
+ *
+ *     const qs = core.url.queryBuilder()
+ *         .add("limit", limit)
+ *         .add("tags", tags, { style: "comma" })   // explode: false
+ *         .mergeAdditional(requestOptions?.queryParams)
+ *         .build();
+ */
+export declare function queryBuilder(): QueryStringBuilder;
+declare class QueryStringBuilder {
+    private parts;
+    /**
+     * Adds a query parameter, serializing it immediately.
+     *
+     * By default arrays use "repeat" format (`key=a&key=b`).
+     * Pass `{ style: "comma" }` for OpenAPI `explode: false` parameters
+     * to get comma-separated values (`key=a,b,c`).
+     *
+     * Null / undefined values are silently skipped.
+     */
+    add(key: string, value: unknown, options?: {
+        style?: "comma";
+    }): this;
+    /**
+     * Adds multiple query parameters at once from a record.
+     * All parameters use the default "repeat" array format.
+     * Null / undefined values are silently skipped.
+     */
+    addMany(params: Record<string, unknown>): this;
+    /**
+     * Merges additional query parameters supplied at call-time via
+     * `requestOptions.queryParams`. Overrides existing keys (last-write-wins).
+     */
+    mergeAdditional(additionalParams?: Record<string, unknown>): this;
+    /**
+     * Returns the assembled query string (without the leading `?`).
+     * Returns an empty string when no parameters were added.
+     */
+    build(): string;
+}
+export {};

package/dist/core/url/QueryStringBuilder.js

@@ -0,0 +1,78 @@
+import { toQueryString } from "./qs.js";
+/**
+ * Creates a fluent builder for constructing URL query strings.
+ *
+ * Each `.add()` call serializes its value immediately (like C#'s builder),
+ * so no format tracking is needed — the style is applied at add-time.
+ *
+ * Usage (generated code):
+ *
+ *     const qs = core.url.queryBuilder()
+ *         .add("limit", limit)
+ *         .add("tags", tags, { style: "comma" })   // explode: false
+ *         .mergeAdditional(requestOptions?.queryParams)
+ *         .build();
+ */
+export function queryBuilder() {
+    return new QueryStringBuilder();
+}
+class QueryStringBuilder {
+    parts = new Map();
+    /**
+     * Adds a query parameter, serializing it immediately.
+     *
+     * By default arrays use "repeat" format (`key=a&key=b`).
+     * Pass `{ style: "comma" }` for OpenAPI `explode: false` parameters
+     * to get comma-separated values (`key=a,b,c`).
+     *
+     * Null / undefined values are silently skipped.
+     */
+    add(key, value, options) {
+        if (value === undefined || value === null) {
+            return this;
+        }
+        const serialized = toQueryString({ [key]: value }, { arrayFormat: options?.style === "comma" ? "comma" : "repeat" });
+        if (serialized.length > 0) {
+            this.parts.set(key, serialized);
+        }
+        return this;
+    }
+    /**
+     * Adds multiple query parameters at once from a record.
+     * All parameters use the default "repeat" array format.
+     * Null / undefined values are silently skipped.
+     */
+    addMany(params) {
+        if (params != null) {
+            for (const [key, value] of Object.entries(params)) {
+                this.add(key, value);
+            }
+        }
+        return this;
+    }
+    /**
+     * Merges additional query parameters supplied at call-time via
+     * `requestOptions.queryParams`. Overrides existing keys (last-write-wins).
+     */
+    mergeAdditional(additionalParams) {
+        if (additionalParams != null) {
+            for (const [key, value] of Object.entries(additionalParams)) {
+                if (value === undefined || value === null) {
+                    continue;
+                }
+                const serialized = toQueryString({ [key]: value }, { arrayFormat: "repeat" });
+                if (serialized.length > 0) {
+                    this.parts.set(key, serialized);
+                }
+            }
+        }
+        return this;
+    }
+    /**
+     * Returns the assembled query string (without the leading `?`).
+     * Returns an empty string when no parameters were added.
+     */
+    build() {
+        return [...this.parts.values()].join("&");
+    }
+}

package/dist/core/url/encodePathParam.d.ts

@@ -0,0 +1 @@
+export declare function encodePathParam(param: unknown): string;

package/dist/core/url/encodePathParam.js

@@ -0,0 +1,18 @@
+export function encodePathParam(param) {
+    if (param === null) {
+        return "null";
+    }
+    const typeofParam = typeof param;
+    switch (typeofParam) {
+        case "undefined":
+            return "undefined";
+        case "string":
+        case "number":
+        case "boolean":
+            break;
+        default:
+            param = String(param);
+            break;
+    }
+    return encodeURIComponent(param);
+}

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

@@ -0,0 +1,4 @@
+export { encodePathParam } from "./encodePathParam.js";
+export { join } from "./join.js";
+export { toQueryString } from "./qs.js";
+export { queryBuilder } from "./QueryStringBuilder.js";

package/dist/core/url/index.js

@@ -0,0 +1,4 @@
+export { encodePathParam } from "./encodePathParam.js";
+export { join } from "./join.js";
+export { toQueryString } from "./qs.js";
+export { queryBuilder } from "./QueryStringBuilder.js";

package/dist/core/url/join.d.ts

@@ -0,0 +1 @@
+export declare function join(base: string, ...segments: string[]): string;

package/dist/core/url/join.js

@@ -0,0 +1,65 @@
+export function join(base, ...segments) {
+    if (!base) {
+        return "";
+    }
+    if (segments.length === 0) {
+        return base;
+    }
+    if (base.includes("://")) {
+        let url;
+        try {
+            url = new URL(base);
+        }
+        catch {
+            return joinPath(base, ...segments);
+        }
+        const lastSegment = segments[segments.length - 1];
+        const shouldPreserveTrailingSlash = lastSegment?.endsWith("/");
+        for (const segment of segments) {
+            const cleanSegment = trimSlashes(segment);
+            if (cleanSegment) {
+                url.pathname = joinPathSegments(url.pathname, cleanSegment);
+            }
+        }
+        if (shouldPreserveTrailingSlash && !url.pathname.endsWith("/")) {
+            url.pathname += "/";
+        }
+        return url.toString();
+    }
+    return joinPath(base, ...segments);
+}
+function joinPath(base, ...segments) {
+    if (segments.length === 0) {
+        return base;
+    }
+    let result = base;
+    const lastSegment = segments[segments.length - 1];
+    const shouldPreserveTrailingSlash = lastSegment?.endsWith("/");
+    for (const segment of segments) {
+        const cleanSegment = trimSlashes(segment);
+        if (cleanSegment) {
+            result = joinPathSegments(result, cleanSegment);
+        }
+    }
+    if (shouldPreserveTrailingSlash && !result.endsWith("/")) {
+        result += "/";
+    }
+    return result;
+}
+function joinPathSegments(left, right) {
+    if (left.endsWith("/")) {
+        return left + right;
+    }
+    return `${left}/${right}`;
+}
+function trimSlashes(str) {
+    if (!str)
+        return str;
+    let start = 0;
+    let end = str.length;
+    if (str.startsWith("/"))
+        start = 1;
+    if (str.endsWith("/"))
+        end = str.length - 1;
+    return start === 0 && end === str.length ? str : str.slice(start, end);
+}

package/dist/core/url/qs.d.ts

@@ -0,0 +1,7 @@
+type ArrayFormat = "indices" | "repeat" | "comma";
+interface QueryStringOptions {
+    arrayFormat?: ArrayFormat;
+    encode?: boolean;
+}
+export declare function toQueryString(obj: unknown, options?: QueryStringOptions): string;
+export {};