@standardserver/core 0.0.0 → 0.0.2

package/dist/event-stream/index.d.mts

@@ -0,0 +1,79 @@
+interface EventStreamMessageMeta {
+    /**
+     * Event identifier, sent back by the client as `lastEventId` for reconnection attempts.
+     *
+     * @warning id cannot contain newline characters (`\n`)
+     */
+    id?: string | undefined;
+    /**
+     * The number of milliseconds the client should wait before attempting to reconnect.
+     */
+    retry?: number | undefined;
+    /**
+     * Comments associated with the event.
+     *
+     * @warning Comments must not contain newline characters (`\n`).
+     */
+    comments?: readonly string[] | undefined;
+}
+interface EventStreamMessage extends EventStreamMessageMeta {
+    /**
+     * Event name (e.g., `message`, `error`).
+     */
+    event?: string | undefined;
+    /**
+     * Event data, typically JSON-encoded.
+     */
+    data?: string | undefined;
+}
+
+declare function decodeEventStreamMessage(encoded: string): EventStreamMessage;
+declare class EventStreamDecoder {
+    private readonly onEvent;
+    private incomplete;
+    constructor(onEvent: (event: EventStreamMessage) => void);
+    feed(chunk: string): void;
+    end(): void;
+}
+declare class EventStreamDecoderStream extends TransformStream<string, EventStreamMessage> {
+    constructor();
+}
+
+declare function assertEventStreamMessageId(id: string): void;
+declare function assertEventStreamMessageName(event: string): void;
+declare function assertEventStreamMessageRetry(retry: number): void;
+declare function assertEventStreamMessageComment(comment: string): void;
+declare function encodeEventStreamMessageData(data: string | undefined): string;
+declare function encodeEventStreamMessageComments(comments: readonly string[] | undefined): string;
+declare function encodeEventStreamMessage(message: EventStreamMessage): string;
+
+declare class EventStreamEncoderError extends TypeError {
+}
+declare class EventStreamDecoderError extends TypeError {
+}
+interface EventIteratorErrorEventOptions extends ErrorOptions {
+    message?: string;
+}
+declare class EventIteratorErrorEvent extends Error {
+    readonly data: unknown;
+    constructor(data: unknown, options?: EventIteratorErrorEventOptions);
+}
+
+declare const EVENT_META_SYMBOL: symbol;
+/**
+ * Attaches event meta information to the provided container.
+ *
+ * @info The returned container is a proxy that intercepts access to the meta symbol.
+ */
+declare function withEventIteratorEventMeta<T extends object>(container: T, meta: EventStreamMessageMeta): T;
+/**
+ * Resolves the event meta information from the provided container.
+ */
+declare function resolveEventIteratorEvent<T>(container: T): [data: T, meta: EventStreamMessageMeta | undefined];
+/**
+ * Retrieves event meta information from the provided container.
+ */
+declare function getEventIteratorEventMeta(container: unknown): EventStreamMessageMeta | undefined;
+
+export { EVENT_META_SYMBOL, EventIteratorErrorEvent, EventStreamDecoder, EventStreamDecoderError, EventStreamDecoderStream, EventStreamEncoderError, assertEventStreamMessageComment, assertEventStreamMessageId, assertEventStreamMessageName, assertEventStreamMessageRetry, decodeEventStreamMessage, encodeEventStreamMessage, encodeEventStreamMessageComments, encodeEventStreamMessageData, getEventIteratorEventMeta, resolveEventIteratorEvent, withEventIteratorEventMeta };
+export type { EventIteratorErrorEventOptions, EventStreamMessage, EventStreamMessageMeta };

package/dist/event-stream/index.d.ts

@@ -0,0 +1,79 @@
+interface EventStreamMessageMeta {
+    /**
+     * Event identifier, sent back by the client as `lastEventId` for reconnection attempts.
+     *
+     * @warning id cannot contain newline characters (`\n`)
+     */
+    id?: string | undefined;
+    /**
+     * The number of milliseconds the client should wait before attempting to reconnect.
+     */
+    retry?: number | undefined;
+    /**
+     * Comments associated with the event.
+     *
+     * @warning Comments must not contain newline characters (`\n`).
+     */
+    comments?: readonly string[] | undefined;
+}
+interface EventStreamMessage extends EventStreamMessageMeta {
+    /**
+     * Event name (e.g., `message`, `error`).
+     */
+    event?: string | undefined;
+    /**
+     * Event data, typically JSON-encoded.
+     */
+    data?: string | undefined;
+}
+
+declare function decodeEventStreamMessage(encoded: string): EventStreamMessage;
+declare class EventStreamDecoder {
+    private readonly onEvent;
+    private incomplete;
+    constructor(onEvent: (event: EventStreamMessage) => void);
+    feed(chunk: string): void;
+    end(): void;
+}
+declare class EventStreamDecoderStream extends TransformStream<string, EventStreamMessage> {
+    constructor();
+}
+
+declare function assertEventStreamMessageId(id: string): void;
+declare function assertEventStreamMessageName(event: string): void;
+declare function assertEventStreamMessageRetry(retry: number): void;
+declare function assertEventStreamMessageComment(comment: string): void;
+declare function encodeEventStreamMessageData(data: string | undefined): string;
+declare function encodeEventStreamMessageComments(comments: readonly string[] | undefined): string;
+declare function encodeEventStreamMessage(message: EventStreamMessage): string;
+
+declare class EventStreamEncoderError extends TypeError {
+}
+declare class EventStreamDecoderError extends TypeError {
+}
+interface EventIteratorErrorEventOptions extends ErrorOptions {
+    message?: string;
+}
+declare class EventIteratorErrorEvent extends Error {
+    readonly data: unknown;
+    constructor(data: unknown, options?: EventIteratorErrorEventOptions);
+}
+
+declare const EVENT_META_SYMBOL: symbol;
+/**
+ * Attaches event meta information to the provided container.
+ *
+ * @info The returned container is a proxy that intercepts access to the meta symbol.
+ */
+declare function withEventIteratorEventMeta<T extends object>(container: T, meta: EventStreamMessageMeta): T;
+/**
+ * Resolves the event meta information from the provided container.
+ */
+declare function resolveEventIteratorEvent<T>(container: T): [data: T, meta: EventStreamMessageMeta | undefined];
+/**
+ * Retrieves event meta information from the provided container.
+ */
+declare function getEventIteratorEventMeta(container: unknown): EventStreamMessageMeta | undefined;
+
+export { EVENT_META_SYMBOL, EventIteratorErrorEvent, EventStreamDecoder, EventStreamDecoderError, EventStreamDecoderStream, EventStreamEncoderError, assertEventStreamMessageComment, assertEventStreamMessageId, assertEventStreamMessageName, assertEventStreamMessageRetry, decodeEventStreamMessage, encodeEventStreamMessage, encodeEventStreamMessageComments, encodeEventStreamMessageData, getEventIteratorEventMeta, resolveEventIteratorEvent, withEventIteratorEventMeta };
+export type { EventIteratorErrorEventOptions, EventStreamMessage, EventStreamMessageMeta };

package/dist/event-stream/index.mjs

@@ -0,0 +1,197 @@
+import { getPackageSymbol, createEnhancedProxy, isTypescriptObject, getEnhancedProxyTarget } from '@standardserver/shared';
+
+class EventStreamEncoderError extends TypeError {
+}
+class EventStreamDecoderError extends TypeError {
+}
+class EventIteratorErrorEvent extends Error {
+  constructor(data, options = {}) {
+    super(options?.message ?? "Error Event", options);
+    this.data = data;
+  }
+}
+
+function decodeEventStreamMessage(encoded) {
+  const lines = encoded.replace(/\n+$/, "").split(/\n/);
+  const message = {};
+  for (const line of lines) {
+    const index = line.indexOf(":");
+    const key = index === -1 ? line : line.slice(0, index);
+    const value = index === -1 ? "" : line.slice(index + 1).replace(/^\s/, "");
+    if (index === 0) {
+      message.comments ??= [];
+      message.comments.push(value);
+    } else if (key === "data") {
+      if (message.data !== void 0) {
+        message.data += `
+${value}`;
+      } else {
+        message.data = value;
+      }
+    } else if (key === "event") {
+      message.event = value;
+    } else if (key === "id") {
+      message.id = value;
+    } else if (key === "retry") {
+      const maybeInteger = Number.parseInt(value);
+      if (Number.isInteger(maybeInteger) && maybeInteger >= 0 && maybeInteger.toString() === value) {
+        message.retry = maybeInteger;
+      }
+    }
+  }
+  return message;
+}
+class EventStreamDecoder {
+  constructor(onEvent) {
+    this.onEvent = onEvent;
+  }
+  incomplete = "";
+  feed(chunk) {
+    this.incomplete += chunk;
+    const lastCompleteIndex = this.incomplete.lastIndexOf("\n\n");
+    if (lastCompleteIndex === -1) {
+      return;
+    }
+    const completes = this.incomplete.slice(0, lastCompleteIndex).split(/\n\n/);
+    this.incomplete = this.incomplete.slice(lastCompleteIndex + 2);
+    for (const encoded of completes) {
+      const message = decodeEventStreamMessage(`${encoded}
+
+`);
+      this.onEvent(message);
+    }
+  }
+  end() {
+    if (this.incomplete) {
+      throw new EventStreamDecoderError("Event Stream ended before complete");
+    }
+  }
+}
+class EventStreamDecoderStream extends TransformStream {
+  constructor() {
+    let decoder;
+    super({
+      start(controller) {
+        decoder = new EventStreamDecoder((event) => {
+          controller.enqueue(event);
+        });
+      },
+      transform(chunk) {
+        decoder.feed(chunk);
+      },
+      flush() {
+        decoder.end();
+      }
+    });
+  }
+}
+
+function assertEventStreamMessageId(id) {
+  if (id.includes("\n")) {
+    throw new EventStreamEncoderError("Event's id must not contain a newline character");
+  }
+}
+function assertEventStreamMessageName(event) {
+  if (event.includes("\n")) {
+    throw new EventStreamEncoderError("Event's event must not contain a newline character");
+  }
+}
+function assertEventStreamMessageRetry(retry) {
+  if (!Number.isInteger(retry) || retry < 0) {
+    throw new EventStreamEncoderError("Event's retry must be a integer and >= 0");
+  }
+}
+function assertEventStreamMessageComment(comment) {
+  if (comment.includes("\n")) {
+    throw new EventStreamEncoderError("Event's comment must not contain a newline character");
+  }
+}
+function encodeEventStreamMessageData(data) {
+  const lines = data?.split(/\n/) ?? [];
+  let output = "";
+  for (const line of lines) {
+    output += `data: ${line}
+`;
+  }
+  return output;
+}
+function encodeEventStreamMessageComments(comments) {
+  let output = "";
+  for (const comment of comments ?? []) {
+    assertEventStreamMessageComment(comment);
+    output += `: ${comment}
+`;
+  }
+  return output;
+}
+function encodeEventStreamMessage(message) {
+  let output = "";
+  output += encodeEventStreamMessageComments(message.comments);
+  if (message.event !== void 0) {
+    assertEventStreamMessageName(message.event);
+    output += `event: ${message.event}
+`;
+  }
+  if (message.retry !== void 0) {
+    assertEventStreamMessageRetry(message.retry);
+    output += `retry: ${message.retry}
+`;
+  }
+  if (message.id !== void 0) {
+    assertEventStreamMessageId(message.id);
+    output += `id: ${message.id}
+`;
+  }
+  output += encodeEventStreamMessageData(message.data);
+  output += "\n";
+  return output;
+}
+
+const EVENT_META_SYMBOL = getPackageSymbol("EVENT_META");
+function withEventIteratorEventMeta(container, meta) {
+  let assertedMeta;
+  if (meta.id !== void 0) {
+    assertEventStreamMessageId(meta.id);
+    assertedMeta ??= {};
+    assertedMeta.id = meta.id;
+  }
+  if (meta.retry !== void 0) {
+    assertEventStreamMessageRetry(meta.retry);
+    assertedMeta ??= {};
+    assertedMeta.retry = meta.retry;
+  }
+  if (meta.comments !== void 0) {
+    for (const comment of meta.comments) {
+      assertEventStreamMessageComment(comment);
+    }
+    assertedMeta ??= {};
+    assertedMeta.comments = meta.comments;
+  }
+  if (!assertedMeta) {
+    return container;
+  }
+  return createEnhancedProxy(container, {
+    get(_target, prop, _receiver, fallback) {
+      if (prop === EVENT_META_SYMBOL) {
+        return assertedMeta;
+      }
+      return fallback();
+    }
+  });
+}
+function resolveEventIteratorEvent(container) {
+  if (!isTypescriptObject(container)) {
+    return [container, void 0];
+  }
+  const meta = Reflect.get(container, EVENT_META_SYMBOL);
+  const target = getEnhancedProxyTarget(container);
+  return [target, meta];
+}
+function getEventIteratorEventMeta(container) {
+  if (!isTypescriptObject(container)) {
+    return void 0;
+  }
+  return Reflect.get(container, EVENT_META_SYMBOL);
+}
+
+export { EVENT_META_SYMBOL, EventIteratorErrorEvent, EventStreamDecoder, EventStreamDecoderError, EventStreamDecoderStream, EventStreamEncoderError, assertEventStreamMessageComment, assertEventStreamMessageId, assertEventStreamMessageName, assertEventStreamMessageRetry, decodeEventStreamMessage, encodeEventStreamMessage, encodeEventStreamMessageComments, encodeEventStreamMessageData, getEventIteratorEventMeta, resolveEventIteratorEvent, withEventIteratorEventMeta };

package/dist/index.d.mts

@@ -1,3 +1,73 @@
-declare const author = "unnoq";
+type StandardMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD' | (string & {});
+type StandardUrl = `/${string}` | `/${string}?${string}` | `/${string}#${string}` | `/${string}?${string}#${string}`;
+interface StandardHeaders {
+    [key: string]: string | string[] | undefined;
+}
+type StandardBodyHint = 'json' | 'form-data' | 'url-search-params' | 'event-stream' | 'octet-stream' | 'file' | 'none';
+type StandardBody = unknown | URLSearchParams | FormData | AsyncIterator<unknown | void, unknown | void, undefined> | ReadableStream<Uint8Array<ArrayBuffer>> | Blob | undefined;
+interface StandardRequest {
+    /**
+     * @example 'GET', 'POST', etc.
+     */
+    method: StandardMethod;
+    /**
+     * @example `/example`, `/example?query=param#fragment`
+     */
+    url: StandardUrl;
+    /**
+     * @example { 'content-type': 'application/json' }
+     */
+    headers: StandardHeaders;
+    /**
+     * The body has been parsed based on the content headers.
+     */
+    body?: StandardBody | undefined;
+    /**
+     * An AbortSignal to communicate aborting of request.
+     */
+    signal?: AbortSignal | undefined;
+}
+interface StandardLazyRequest extends Omit<StandardRequest, 'body'> {
+    /**
+     * Lazily resolves the body.
+     *
+     * The body is parsed on first call based on the `Content-Type` header
+     * or the provided hint.
+     *
+     * Calling this method may consume the underlying stream.
+     */
+    resolveBody: (hint?: StandardBodyHint | undefined) => Promise<StandardBody>;
+}
+interface StandardResponse {
+    /**
+     * @example 200, 404, 500, etc.
+     */
+    status: number;
+    /**
+     * @example { 'set-cookie': ['sessionId=abc123; HttpOnly'] }
+     */
+    headers: StandardHeaders;
+    /**
+     * The body has been parsed based on the content headers.
+     */
+    body?: StandardBody | undefined;
+}
+interface StandardLazyResponse extends Omit<StandardResponse, 'body'> {
+    /**
+     * Lazily resolves the body.
+     *
+     * The body is parsed on first call based on the `Content-Type` header
+     * or the provided hint.
+     *
+     * Calling this method may consume the underlying stream.
+     */
+    resolveBody: (hint?: StandardBodyHint | undefined) => Promise<StandardBody>;
+}
 
-export { author };
+declare function generateContentDisposition(filename: string): string;
+declare function getFilenameFromContentDisposition(contentDisposition: string): string | undefined;
+declare function flattenStandardHeader(header: string | readonly string[] | undefined): string | undefined;
+declare function mergeStandardHeaders(a: StandardHeaders, b: StandardHeaders): StandardHeaders;
+
+export { flattenStandardHeader, generateContentDisposition, getFilenameFromContentDisposition, mergeStandardHeaders };
+export type { StandardBody, StandardBodyHint, StandardHeaders, StandardLazyRequest, StandardLazyResponse, StandardMethod, StandardRequest, StandardResponse, StandardUrl };

package/dist/index.d.ts

@@ -1,3 +1,73 @@
-declare const author = "unnoq";
+type StandardMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD' | (string & {});
+type StandardUrl = `/${string}` | `/${string}?${string}` | `/${string}#${string}` | `/${string}?${string}#${string}`;
+interface StandardHeaders {
+    [key: string]: string | string[] | undefined;
+}
+type StandardBodyHint = 'json' | 'form-data' | 'url-search-params' | 'event-stream' | 'octet-stream' | 'file' | 'none';
+type StandardBody = unknown | URLSearchParams | FormData | AsyncIterator<unknown | void, unknown | void, undefined> | ReadableStream<Uint8Array<ArrayBuffer>> | Blob | undefined;
+interface StandardRequest {
+    /**
+     * @example 'GET', 'POST', etc.
+     */
+    method: StandardMethod;
+    /**
+     * @example `/example`, `/example?query=param#fragment`
+     */
+    url: StandardUrl;
+    /**
+     * @example { 'content-type': 'application/json' }
+     */
+    headers: StandardHeaders;
+    /**
+     * The body has been parsed based on the content headers.
+     */
+    body?: StandardBody | undefined;
+    /**
+     * An AbortSignal to communicate aborting of request.
+     */
+    signal?: AbortSignal | undefined;
+}
+interface StandardLazyRequest extends Omit<StandardRequest, 'body'> {
+    /**
+     * Lazily resolves the body.
+     *
+     * The body is parsed on first call based on the `Content-Type` header
+     * or the provided hint.
+     *
+     * Calling this method may consume the underlying stream.
+     */
+    resolveBody: (hint?: StandardBodyHint | undefined) => Promise<StandardBody>;
+}
+interface StandardResponse {
+    /**
+     * @example 200, 404, 500, etc.
+     */
+    status: number;
+    /**
+     * @example { 'set-cookie': ['sessionId=abc123; HttpOnly'] }
+     */
+    headers: StandardHeaders;
+    /**
+     * The body has been parsed based on the content headers.
+     */
+    body?: StandardBody | undefined;
+}
+interface StandardLazyResponse extends Omit<StandardResponse, 'body'> {
+    /**
+     * Lazily resolves the body.
+     *
+     * The body is parsed on first call based on the `Content-Type` header
+     * or the provided hint.
+     *
+     * Calling this method may consume the underlying stream.
+     */
+    resolveBody: (hint?: StandardBodyHint | undefined) => Promise<StandardBody>;
+}
 
-export { author };
+declare function generateContentDisposition(filename: string): string;
+declare function getFilenameFromContentDisposition(contentDisposition: string): string | undefined;
+declare function flattenStandardHeader(header: string | readonly string[] | undefined): string | undefined;
+declare function mergeStandardHeaders(a: StandardHeaders, b: StandardHeaders): StandardHeaders;
+
+export { flattenStandardHeader, generateContentDisposition, getFilenameFromContentDisposition, mergeStandardHeaders };
+export type { StandardBody, StandardBodyHint, StandardHeaders, StandardLazyRequest, StandardLazyResponse, StandardMethod, StandardRequest, StandardResponse, StandardUrl };

package/dist/index.mjs

@@ -1,3 +1,45 @@
-const author = "unnoq";
+import { tryDecodeURIComponent, toArray } from '@standardserver/shared';
 
-export { author };
+function generateContentDisposition(filename) {
+  const escapedFileName = filename.replace(/"/g, '\\"');
+  const encodedFilenameStar = encodeURIComponent(filename).replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`).replace(/%(7C|60|5E)/g, (str, hex) => String.fromCharCode(Number.parseInt(hex, 16)));
+  return `inline; filename="${escapedFileName}"; filename*=utf-8''${encodedFilenameStar}`;
+}
+function getFilenameFromContentDisposition(contentDisposition) {
+  const encodedFilenameStarMatch = contentDisposition.match(/filename\*=(UTF-8'')?([^;]*)/i);
+  if (encodedFilenameStarMatch && typeof encodedFilenameStarMatch[2] === "string") {
+    return tryDecodeURIComponent(encodedFilenameStarMatch[2]);
+  }
+  const encodedFilenameMatch = contentDisposition.match(/filename="((?:\\"|[^"])*)"/i);
+  if (encodedFilenameMatch && typeof encodedFilenameMatch[1] === "string") {
+    return encodedFilenameMatch[1].replace(/\\"/g, '"');
+  }
+}
+function flattenStandardHeader(header) {
+  if (typeof header === "string" || header === void 0) {
+    return header;
+  }
+  if (header.length === 0) {
+    return void 0;
+  }
+  return header.join(", ");
+}
+function mergeStandardHeaders(a, b) {
+  const merged = { ...a };
+  for (const key in b) {
+    if (Array.isArray(b[key])) {
+      merged[key] = [...toArray(merged[key]), ...b[key]];
+    } else if (b[key] !== void 0) {
+      if (Array.isArray(merged[key])) {
+        merged[key] = [...merged[key], b[key]];
+      } else if (merged[key] !== void 0) {
+        merged[key] = [merged[key], b[key]];
+      } else {
+        merged[key] = b[key];
+      }
+    }
+  }
+  return merged;
+}
+
+export { flattenStandardHeader, generateContentDisposition, getFilenameFromContentDisposition, mergeStandardHeaders };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@standardserver/core",
   "type": "module",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "license": "MIT",
   "homepage": "https://standardserver.dev",
   "repository": {
@@ -14,11 +14,19 @@
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs",
       "default": "./dist/index.mjs"
+    },
+    "./event-stream": {
+      "types": "./dist/event-stream/index.d.mts",
+      "import": "./dist/event-stream/index.mjs",
+      "default": "./dist/event-stream/index.mjs"
     }
   },
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "@standardserver/shared": "0.0.2"
+  },
   "scripts": {
     "build": "unbuild",
     "type:check": "tsc -b"