@standardserver/core 0.0.15 → 0.0.19

package/README.md

@@ -0,0 +1,308 @@
+# @standardserver/core
+
+<div align="center">
+  <a href="https://codecov.io/gh/middleapi/standardserver">
+    <img alt="codecov" src="https://codecov.io/gh/middleapi/standardserver/branch/main/graph/badge.svg">
+  </a>
+  <a href="https://www.npmjs.com/package/@standardserver/core">
+    <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40standardserver%2Fcore?logo=npm" />
+  </a>
+  <a href="https://github.com/middleapi/standardserver/blob/main/LICENSE">
+    <img alt="MIT License" src="https://img.shields.io/github/license/middleapi/standardserver?logo=open-source-initiative" />
+  </a>
+  <a href="https://discord.gg/TXEbwRBvQn">
+    <img alt="Discord" src="https://img.shields.io/discord/1308966753044398161?color=7389D8&label&logo=discord&logoColor=ffffff" />
+  </a>
+  <a href="https://deepwiki.com/middleapi/standardserver">
+    <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
+  </a>
+</div>
+
+`@standardserver/core` is the shared contract package for Standard Server.
+
+Standard Server provides a unified interface for client-server communication across HTTP and message-based transports. It lets you keep handler and client code transport-agnostic by working with the same request, response, body, and streaming abstractions whether the transport is Fetch, Node.js HTTP, or a peer-style message channel.
+
+This package is the foundation of that model. It defines the core request and response types, shared runtime validators, small utility helpers, and event stream (SSE) helpers.
+
+## Entry Points
+
+| Entry point            | Purpose                                                  |
+| ---------------------- | -------------------------------------------------------- |
+| `@standardserver/core` | Shared request/response types, utilities, and validators |
+
+## Request and response types
+
+The main entry point exposes four transport-agnostic shapes:
+
+| Export                 | Description                                                     |
+| ---------------------- | --------------------------------------------------------------- |
+| `StandardRequest`      | Eager request object with a parsed `body`                       |
+| `StandardLazyRequest`  | Request object with `resolveBody(hint?)` for lazy body parsing  |
+| `StandardResponse`     | Eager response object with a parsed `body`                      |
+| `StandardLazyResponse` | Response object with `resolveBody(hint?)` for lazy body parsing |
+
+Supporting primitives:
+
+| Export             | Description                                                   |
+| ------------------ | ------------------------------------------------------------- |
+| `StandardMethod`   | Common HTTP verbs plus any custom string value                |
+| `StandardUrl`      | A request URL that must start with `/` and exclude the origin |
+| `StandardHeaders`  | `Record<string, string \| string[] \| undefined>`             |
+| `StandardBodyHint` | Parsing hint for lazy body resolution                         |
+| `StandardBody`     | Shared body union used by requests and responses              |
+
+By convention, adapters normalize headers to lowercase keys. `signal` is part of `StandardRequest` only and is used to propagate request cancellation.
+
+```ts
+import type { StandardLazyRequest, StandardResponse } from '@standardserver/core'
+
+export async function handle(request: StandardLazyRequest): Promise<StandardResponse> {
+  const body = await request.resolveBody()
+
+  return {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+    body: {
+      ok: true,
+      method: request.method,
+      url: request.url,
+      received: body,
+    },
+  }
+}
+```
+
+### Body hints and body values
+
+`StandardBodyHint` and `StandardBody` describe the shared body contract used across adapters:
+
+| Hint                | `StandardBody` value           | Typical content type                | Notes                                                 |
+| ------------------- | ------------------------------ | ----------------------------------- | ----------------------------------------------------- |
+| `json`              | `unknown`                      | `application/json`                  | Primitives, objects, and arrays                       |
+| `form-data`         | `FormData`                     | `multipart/form-data`               | Multipart form submissions                            |
+| `url-search-params` | `URLSearchParams`              | `application/x-www-form-urlencoded` | URL-encoded forms                                     |
+| `event-stream`      | `AsyncIteratorObject<unknown>` | `text/event-stream`                 | Server-Sent Events (SSE)                              |
+| `octet-stream`      | `ReadableStream<Uint8Array>`   | any                                 | Binary payloads                                       |
+| `file`              | `File`                         | any                                 | Fixed-size binary payloads for both `File` and `Blob` |
+| `none`              | `undefined`                    |                                     | Empty body                                            |
+
+### Resolving Body
+
+`resolveBody(hint?)` determines how to parse the body using the following priority:
+
+1. If the `standard-server` header is present, use it as the `StandardBodyHint`.
+2. Otherwise, if `hint?` is provided, use it as the `StandardBodyHint`.
+3. Otherwise, if `content-type` is one of the common types, parse accordingly.
+4. Otherwise, if `content-length` exists, treat the body as `file`; if not, treat it as `octet-stream`.
+
+For efficient communication, set the `standard-server` header to explicitly hint the body type, especially for file or binary streaming. For example, if you upload a file with a common `content-type` such as `application/json` but omit the `standard-server` header, the server may interpret it as JSON and parse it unexpectedly.
+
+```ts
+const response = await fetch('/upload', {
+  method: 'POST',
+  headers: {
+    'content-type': 'application/json',
+    'standard-server': 'file', // <- hint the body type to avoid misinterpretation
+  },
+  body: new Blob(['{"message": "Hello, world!"}'], { type: 'application/json' }),
+})
+```
+
+## Utilities
+
+The main entry point also exports a small set of helpers for common header and URL operations.
+
+### Content-Disposition helpers
+
+Use `generateContentDisposition()` to produce a safe `Content-Disposition` value and `getFilenameFromContentDisposition()` to read a filename back from an existing header.
+
+```ts
+import {
+  generateContentDisposition,
+  getFilenameFromContentDisposition,
+} from '@standardserver/core'
+
+const disposition = generateContentDisposition('report "Q2".csv')
+// inline; filename="report \"Q2\".csv"; filename*=utf-8''report%20%22Q2%22.csv
+
+const filename = getFilenameFromContentDisposition(disposition)
+// 'report "Q2".csv'
+```
+
+`generateContentDisposition()` preserves an ASCII-safe `filename="..."` value and also emits `filename*=` for UTF-8 aware clients.
+
+### Header helpers
+
+`mergeStandardHeaders()` combines two `StandardHeaders` objects while preserving duplicate values, and `flattenStandardHeader()` turns a single header value into a plain string when needed.
+
+```ts
+import {
+  flattenStandardHeader,
+  mergeStandardHeaders,
+} from '@standardserver/core'
+
+const headers = mergeStandardHeaders(
+  { 'accept': 'application/json', 'set-cookie': ['a=1'] },
+  { 'set-cookie': 'b=2', 'vary': 'accept', 'warning': undefined },
+)
+// {
+//   accept: 'application/json',
+//   'set-cookie': ['a=1', 'b=2'],
+//   vary: 'accept',
+// }
+
+const cookieHeader = flattenStandardHeader(headers['set-cookie'])
+// 'a=1, b=2'
+```
+
+### URL parsing
+
+`parseStandardUrl()` splits a `StandardUrl` into `[pathname, search, hash]` without requiring a full origin.
+
+```ts
+import { parseStandardUrl } from '@standardserver/core'
+
+const [pathname, search, hash] = parseStandardUrl('/users/123?tab=settings#profile')
+// pathname => '/users/123'
+// search => '?tab=settings'
+// hash => '#profile'
+```
+
+## Validators
+
+Runtime type guards are useful when requests or responses cross process, transport, or message boundaries.
+
+| Export                 | Checks                                                 |
+| ---------------------- | ------------------------------------------------------ |
+| `isStandardMethod()`   | Any string value                                       |
+| `isStandardUrl()`      | A string starting with `/`                             |
+| `isStandardHeaders()`  | Object values are `string`, `string[]`, or `undefined` |
+| `isStandardRequest()`  |                                                        |
+| `isStandardResponse()` |                                                        |
+
+```ts
+import { isStandardRequest } from '@standardserver/core'
+
+export function expectStandardRequest(input: unknown) {
+  if (!isStandardRequest(input)) {
+    throw new TypeError('Expected a StandardRequest-compatible value')
+  }
+
+  return input
+}
+```
+
+## Event-Stream Helpers
+
+Use Event-Stream Helpers when you need explicit SSE encoding, decoding, or metadata handling.
+
+### Message types and codecs
+
+The event-stream entry point exposes:
+
+- `EventStreamMessageMeta` for `id`, `retry`, and `comments`
+- `EventStreamMessage` for complete SSE messages
+- `encodeEventStreamMessage()` and `decodeEventStreamMessage()` for single-message codec operations
+- `EventStreamDecoder` and `EventStreamDecoderStream` for chunked stream decoding
+
+```ts
+import {
+  decodeEventStreamMessage,
+  encodeEventStreamMessage,
+} from '@standardserver/core'
+
+const encoded = encodeEventStreamMessage({
+  comments: ['bootstrap'],
+  event: 'message',
+  id: '42',
+  retry: 3000,
+  data: 'hello\nworld',
+})
+
+const decoded = decodeEventStreamMessage(encoded)
+// {
+//   comments: ['bootstrap'],
+//   event: 'message',
+//   id: '42',
+//   retry: 3000,
+//   data: 'hello\nworld',
+// }
+```
+
+For streaming decode, pipe text chunks through `EventStreamDecoderStream`:
+
+```ts
+import { EventStreamDecoderStream } from '@standardserver/core'
+
+const messages = response.body!
+  .pipeThrough(new TextDecoderStream())
+  .pipeThrough(new EventStreamDecoderStream())
+```
+
+### Iterator metadata helpers
+
+`StandardBody` uses async iterators for event-stream bodies. To attach SSE metadata to a yielded value without changing its visible shape, use `withEventIteratorEventMeta()`.
+
+```ts
+import type { StandardResponse } from '@standardserver/core'
+import {
+  unwrapEventIteratorEvent,
+  withEventIteratorEventMeta,
+} from '@standardserver/core'
+
+const eventValue = withEventIteratorEventMeta(
+  { message: 'hello' },
+  { id: '1', retry: 3000, comments: ['bootstrap'] },
+)
+
+const [data, meta] = unwrapEventIteratorEvent(eventValue)
+// data => { message: 'hello' }
+// meta => { id: '1', retry: 3000, comments: ['bootstrap'] }
+
+const response: StandardResponse = {
+  status: 200,
+  headers: {},
+  async* body() {
+    yield eventValue
+  },
+}
+```
+
+> [!WARNING]
+> Metadata is validated before it is attached: `id`, `event`, and comments must not contain line breaks, and `retry` must be a non-negative integer.
+
+### Errors and low-level assertions
+
+The subpath also exports:
+
+- `EventStreamEncoderError` for invalid outbound SSE messages
+- `EventStreamDecoderError` for incomplete or invalid inbound stream decoding
+- `EventIteratorErrorEvent` for wrapping structured event-stream error payloads in an `Error`
+- `assertEventStreamMessageId()`, `assertEventStreamMessageName()`, `assertEventStreamMessageRetry()`, and `assertEventStreamMessageComment()` for low-level validation when building custom SSE tooling
+
+```ts
+import { EventIteratorErrorEvent } from '@standardserver/core'
+
+const error = new EventIteratorErrorEvent(
+  { code: 'E_STREAM', detail: 'Connection lost' },
+  { message: 'stream error' },
+)
+
+error.message
+// 'stream error'
+
+error.data
+// { code: 'E_STREAM', detail: 'Connection lost' }
+```
+
+## Learn more
+
+For the higher-level project overview, see the root [Standard Server README](../../README.md).
+
+## Sponsors
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/gh/middleapi/static/sponsors.svg">
+    <img src='https://cdn.jsdelivr.net/gh/middleapi/static/sponsors.svg' alt="Sponsors"/>
+  </a>
+</p>

package/dist/index.d.mts

@@ -1,3 +1,80 @@
+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?: 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;
+    private trailingCR;
+    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_ITERATOR_EVENT_META_SYMBOL: unique symbol;
+declare const EVENT_ITERATOR_EVENT_SOURCE_SYMBOL: unique symbol;
+/**
+ * Returns a new iterator *event value* with attached, validated metadata.
+ */
+declare function withEventIteratorEventMeta<T extends object>(container: T, meta: EventStreamMessageMeta): T;
+/**
+ * Unwraps an iterator event value and extracts its associated metadata.
+ */
+declare function unwrapEventIteratorEvent<T>(container: T): [data: T, meta: EventStreamMessageMeta | undefined];
+/**
+ * Retrieves metadata attached to a single iterator event value.
+ */
+declare function getEventIteratorEventMeta(container: unknown): EventStreamMessageMeta | undefined;
+
 type StandardMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD' | (string & {});
 type StandardUrl = `/${string}` | `/${string}?${string}` | `/${string}#${string}` | `/${string}?${string}#${string}`;
 interface StandardHeaders {
@@ -80,5 +157,5 @@ declare function isStandardHeaders(maybe: unknown): maybe is StandardHeaders;
 declare function isStandardRequest(maybe: unknown): maybe is StandardRequest;
 declare function isStandardResponse(maybe: unknown): maybe is StandardResponse;
 
-export { flattenStandardHeader, generateContentDisposition, getFilenameFromContentDisposition, isStandardHeaders, isStandardMethod, isStandardRequest, isStandardResponse, isStandardUrl, mergeStandardHeaders, parseStandardUrl };
-export type { StandardBody, StandardBodyHint, StandardHeaders, StandardLazyRequest, StandardLazyResponse, StandardMethod, StandardRequest, StandardResponse, StandardUrl };
+export { EVENT_ITERATOR_EVENT_META_SYMBOL, EVENT_ITERATOR_EVENT_SOURCE_SYMBOL, EventIteratorErrorEvent, EventStreamDecoder, EventStreamDecoderError, EventStreamDecoderStream, EventStreamEncoderError, assertEventStreamMessageComment, assertEventStreamMessageId, assertEventStreamMessageName, assertEventStreamMessageRetry, decodeEventStreamMessage, encodeEventStreamMessage, encodeEventStreamMessageComments, encodeEventStreamMessageData, flattenStandardHeader, generateContentDisposition, getEventIteratorEventMeta, getFilenameFromContentDisposition, isStandardHeaders, isStandardMethod, isStandardRequest, isStandardResponse, isStandardUrl, mergeStandardHeaders, parseStandardUrl, unwrapEventIteratorEvent, withEventIteratorEventMeta };
+export type { EventIteratorErrorEventOptions, EventStreamMessage, EventStreamMessageMeta, StandardBody, StandardBodyHint, StandardHeaders, StandardLazyRequest, StandardLazyResponse, StandardMethod, StandardRequest, StandardResponse, StandardUrl };

package/dist/index.d.ts

@@ -1,3 +1,80 @@
+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?: 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;
+    private trailingCR;
+    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_ITERATOR_EVENT_META_SYMBOL: unique symbol;
+declare const EVENT_ITERATOR_EVENT_SOURCE_SYMBOL: unique symbol;
+/**
+ * Returns a new iterator *event value* with attached, validated metadata.
+ */
+declare function withEventIteratorEventMeta<T extends object>(container: T, meta: EventStreamMessageMeta): T;
+/**
+ * Unwraps an iterator event value and extracts its associated metadata.
+ */
+declare function unwrapEventIteratorEvent<T>(container: T): [data: T, meta: EventStreamMessageMeta | undefined];
+/**
+ * Retrieves metadata attached to a single iterator event value.
+ */
+declare function getEventIteratorEventMeta(container: unknown): EventStreamMessageMeta | undefined;
+
 type StandardMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD' | (string & {});
 type StandardUrl = `/${string}` | `/${string}?${string}` | `/${string}#${string}` | `/${string}?${string}#${string}`;
 interface StandardHeaders {
@@ -80,5 +157,5 @@ declare function isStandardHeaders(maybe: unknown): maybe is StandardHeaders;
 declare function isStandardRequest(maybe: unknown): maybe is StandardRequest;
 declare function isStandardResponse(maybe: unknown): maybe is StandardResponse;
 
-export { flattenStandardHeader, generateContentDisposition, getFilenameFromContentDisposition, isStandardHeaders, isStandardMethod, isStandardRequest, isStandardResponse, isStandardUrl, mergeStandardHeaders, parseStandardUrl };
-export type { StandardBody, StandardBodyHint, StandardHeaders, StandardLazyRequest, StandardLazyResponse, StandardMethod, StandardRequest, StandardResponse, StandardUrl };
+export { EVENT_ITERATOR_EVENT_META_SYMBOL, EVENT_ITERATOR_EVENT_SOURCE_SYMBOL, EventIteratorErrorEvent, EventStreamDecoder, EventStreamDecoderError, EventStreamDecoderStream, EventStreamEncoderError, assertEventStreamMessageComment, assertEventStreamMessageId, assertEventStreamMessageName, assertEventStreamMessageRetry, decodeEventStreamMessage, encodeEventStreamMessage, encodeEventStreamMessageComments, encodeEventStreamMessageData, flattenStandardHeader, generateContentDisposition, getEventIteratorEventMeta, getFilenameFromContentDisposition, isStandardHeaders, isStandardMethod, isStandardRequest, isStandardResponse, isStandardUrl, mergeStandardHeaders, parseStandardUrl, unwrapEventIteratorEvent, withEventIteratorEventMeta };
+export type { EventIteratorErrorEventOptions, EventStreamMessage, EventStreamMessageMeta, StandardBody, StandardBodyHint, StandardHeaders, StandardLazyRequest, StandardLazyResponse, StandardMethod, StandardRequest, StandardResponse, StandardUrl };

package/dist/index.mjs

@@ -1,4 +1,210 @@
-import { tryDecodeURIComponent, toArray, isTypescriptObject } from '@standardserver/shared';
+import { getOrBind, isTypescriptObject, tryDecodeURIComponent, toArray } 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;
+  }
+}
+
+const EVENT_STREAM_LINE_DELIMITER_REGEX = /\r\n|[\n\r]/;
+const EVENT_STREAM_DELIMITER_REGEX = /(?:\r\n|\r(?!\n)|\n)(?:\r\n|\r(?!\n)|\n)/;
+const LEADING_WHITESPACE_REGEX = /^\s/;
+function decodeEventStreamMessage(encoded) {
+  const lines = encoded.split(EVENT_STREAM_LINE_DELIMITER_REGEX);
+  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(LEADING_WHITESPACE_REGEX, "");
+    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 = "";
+  trailingCR = false;
+  feed(chunk) {
+    if (this.trailingCR && chunk.startsWith("\n")) {
+      chunk = chunk.slice(1);
+    }
+    this.trailingCR = chunk.endsWith("\r");
+    this.incomplete += chunk;
+    const parts = this.incomplete.split(EVENT_STREAM_DELIMITER_REGEX);
+    this.incomplete = parts.pop();
+    for (const encoded of parts) {
+      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();
+      }
+    });
+  }
+}
+
+const EVENT_STREAM_LINE_ENDING_REGEX = /\r\n|[\n\r]/;
+function containsEventStreamLineBreak(value) {
+  return EVENT_STREAM_LINE_ENDING_REGEX.test(value);
+}
+function assertEventStreamMessageId(id) {
+  if (containsEventStreamLineBreak(id)) {
+    throw new EventStreamEncoderError("Event's id must not contain a carriage return or newline character");
+  }
+}
+function assertEventStreamMessageName(event) {
+  if (containsEventStreamLineBreak(event)) {
+    throw new EventStreamEncoderError("Event's event must not contain a carriage return or 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 (containsEventStreamLineBreak(comment)) {
+    throw new EventStreamEncoderError("Event's comment must not contain a carriage return or newline character");
+  }
+}
+function encodeEventStreamMessageData(data) {
+  let output = "";
+  if (data !== void 0) {
+    const lines = data.split(EVENT_STREAM_LINE_ENDING_REGEX);
+    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_ITERATOR_EVENT_META_SYMBOL = Symbol.for("STANDARDSERVER_EVENT_ITERATOR_EVENT_META");
+const EVENT_ITERATOR_EVENT_SOURCE_SYMBOL = Symbol.for("STANDARDSERVER_EVENT_ITERATOR_EVENT_SOURCE");
+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 new Proxy(container, {
+    get(target, prop, _receiver) {
+      if (prop === EVENT_ITERATOR_EVENT_SOURCE_SYMBOL) {
+        return target;
+      }
+      if (prop === EVENT_ITERATOR_EVENT_META_SYMBOL) {
+        return assertedMeta;
+      }
+      return getOrBind(target, prop);
+    }
+  });
+}
+function unwrapEventIteratorEvent(container) {
+  if (!isTypescriptObject(container)) {
+    return [container, void 0];
+  }
+  const meta = container[EVENT_ITERATOR_EVENT_META_SYMBOL];
+  const target = container[EVENT_ITERATOR_EVENT_SOURCE_SYMBOL] ?? container;
+  return [target, meta];
+}
+function getEventIteratorEventMeta(container) {
+  if (!isTypescriptObject(container)) {
+    return void 0;
+  }
+  return container[EVENT_ITERATOR_EVENT_META_SYMBOL];
+}
 
 function generateContentDisposition(filename) {
   const encodedFilename = filename.replace(/[^\x20-\x7E]/g, "_").replace(/"/g, '\\"');
@@ -86,4 +292,4 @@ function isStandardResponse(maybe) {
   return isStandardHeaders(maybe.headers);
 }
 
-export { flattenStandardHeader, generateContentDisposition, getFilenameFromContentDisposition, isStandardHeaders, isStandardMethod, isStandardRequest, isStandardResponse, isStandardUrl, mergeStandardHeaders, parseStandardUrl };
+export { EVENT_ITERATOR_EVENT_META_SYMBOL, EVENT_ITERATOR_EVENT_SOURCE_SYMBOL, EventIteratorErrorEvent, EventStreamDecoder, EventStreamDecoderError, EventStreamDecoderStream, EventStreamEncoderError, assertEventStreamMessageComment, assertEventStreamMessageId, assertEventStreamMessageName, assertEventStreamMessageRetry, decodeEventStreamMessage, encodeEventStreamMessage, encodeEventStreamMessageComments, encodeEventStreamMessageData, flattenStandardHeader, generateContentDisposition, getEventIteratorEventMeta, getFilenameFromContentDisposition, isStandardHeaders, isStandardMethod, isStandardRequest, isStandardResponse, isStandardUrl, mergeStandardHeaders, parseStandardUrl, unwrapEventIteratorEvent, withEventIteratorEventMeta };

package/package.json

@@ -1,32 +1,28 @@
 {
   "name": "@standardserver/core",
   "type": "module",
-  "version": "0.0.15",
+  "version": "0.0.19",
   "license": "MIT",
   "homepage": "https://standardserver.dev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/standardserver/standardserver.git",
+    "url": "git+https://github.com/middleapi/standardserver.git",
     "directory": "packages/core"
   },
   "sideEffects": false,
   "exports": {
+    "./package.json": "./package.json",
     ".": {
       "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.15"
+    "@standardserver/shared": "0.0.19"
   },
   "scripts": {
     "build": "unbuild",

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

@@ -1,79 +0,0 @@
-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?: 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;
-    private trailingCR;
-    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_ITERATOR_EVENT_META_SYMBOL: symbol;
-declare const EVENT_ITERATOR_EVENT_SOURCE_SYMBOL: symbol;
-/**
- * Returns a new iterator *event value* with attached, validated metadata.
- */
-declare function withEventIteratorEventMeta<T extends object>(container: T, meta: EventStreamMessageMeta): T;
-/**
- * Unwraps an iterator event value and extracts its associated metadata.
- */
-declare function unwrapEventIteratorEvent<T>(container: T): [data: T, meta: EventStreamMessageMeta | undefined];
-/**
- * Retrieves metadata attached to a single iterator event value.
- */
-declare function getEventIteratorEventMeta(container: unknown): EventStreamMessageMeta | undefined;
-
-export { EVENT_ITERATOR_EVENT_META_SYMBOL, EVENT_ITERATOR_EVENT_SOURCE_SYMBOL, EventIteratorErrorEvent, EventStreamDecoder, EventStreamDecoderError, EventStreamDecoderStream, EventStreamEncoderError, assertEventStreamMessageComment, assertEventStreamMessageId, assertEventStreamMessageName, assertEventStreamMessageRetry, decodeEventStreamMessage, encodeEventStreamMessage, encodeEventStreamMessageComments, encodeEventStreamMessageData, getEventIteratorEventMeta, unwrapEventIteratorEvent, withEventIteratorEventMeta };
-export type { EventIteratorErrorEventOptions, EventStreamMessage, EventStreamMessageMeta };

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

@@ -1,79 +0,0 @@
-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?: 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;
-    private trailingCR;
-    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_ITERATOR_EVENT_META_SYMBOL: symbol;
-declare const EVENT_ITERATOR_EVENT_SOURCE_SYMBOL: symbol;
-/**
- * Returns a new iterator *event value* with attached, validated metadata.
- */
-declare function withEventIteratorEventMeta<T extends object>(container: T, meta: EventStreamMessageMeta): T;
-/**
- * Unwraps an iterator event value and extracts its associated metadata.
- */
-declare function unwrapEventIteratorEvent<T>(container: T): [data: T, meta: EventStreamMessageMeta | undefined];
-/**
- * Retrieves metadata attached to a single iterator event value.
- */
-declare function getEventIteratorEventMeta(container: unknown): EventStreamMessageMeta | undefined;
-
-export { EVENT_ITERATOR_EVENT_META_SYMBOL, EVENT_ITERATOR_EVENT_SOURCE_SYMBOL, EventIteratorErrorEvent, EventStreamDecoder, EventStreamDecoderError, EventStreamDecoderStream, EventStreamEncoderError, assertEventStreamMessageComment, assertEventStreamMessageId, assertEventStreamMessageName, assertEventStreamMessageRetry, decodeEventStreamMessage, encodeEventStreamMessage, encodeEventStreamMessageComments, encodeEventStreamMessageData, getEventIteratorEventMeta, unwrapEventIteratorEvent, withEventIteratorEventMeta };
-export type { EventIteratorErrorEventOptions, EventStreamMessage, EventStreamMessageMeta };

package/dist/event-stream/index.mjs

@@ -1,209 +0,0 @@
-import { getPackageSymbol, getOrBind, isTypescriptObject } 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;
-  }
-}
-
-const EVENT_STREAM_LINE_DELIMITER_REGEX = /\r\n|[\n\r]/;
-const EVENT_STREAM_DELIMITER_REGEX = /(?:\r\n|\r(?!\n)|\n)(?:\r\n|\r(?!\n)|\n)/;
-const LEADING_WHITESPACE_REGEX = /^\s/;
-function decodeEventStreamMessage(encoded) {
-  const lines = encoded.split(EVENT_STREAM_LINE_DELIMITER_REGEX);
-  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(LEADING_WHITESPACE_REGEX, "");
-    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 = "";
-  trailingCR = false;
-  feed(chunk) {
-    if (this.trailingCR && chunk.startsWith("\n")) {
-      chunk = chunk.slice(1);
-    }
-    this.trailingCR = chunk.endsWith("\r");
-    this.incomplete += chunk;
-    const parts = this.incomplete.split(EVENT_STREAM_DELIMITER_REGEX);
-    this.incomplete = parts.pop();
-    for (const encoded of parts) {
-      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();
-      }
-    });
-  }
-}
-
-const EVENT_STREAM_LINE_ENDING_REGEX = /\r\n|[\n\r]/;
-function containsEventStreamLineBreak(value) {
-  return EVENT_STREAM_LINE_ENDING_REGEX.test(value);
-}
-function assertEventStreamMessageId(id) {
-  if (containsEventStreamLineBreak(id)) {
-    throw new EventStreamEncoderError("Event's id must not contain a carriage return or newline character");
-  }
-}
-function assertEventStreamMessageName(event) {
-  if (containsEventStreamLineBreak(event)) {
-    throw new EventStreamEncoderError("Event's event must not contain a carriage return or 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 (containsEventStreamLineBreak(comment)) {
-    throw new EventStreamEncoderError("Event's comment must not contain a carriage return or newline character");
-  }
-}
-function encodeEventStreamMessageData(data) {
-  let output = "";
-  if (data !== void 0) {
-    const lines = data.split(EVENT_STREAM_LINE_ENDING_REGEX);
-    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_ITERATOR_EVENT_META_SYMBOL = getPackageSymbol("EVENT_ITERATOR_EVENT_META");
-const EVENT_ITERATOR_EVENT_SOURCE_SYMBOL = getPackageSymbol("EVENT_ITERATOR_EVENT_SOURCE");
-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 new Proxy(container, {
-    get(target, prop, _receiver) {
-      if (prop === EVENT_ITERATOR_EVENT_SOURCE_SYMBOL) {
-        return target;
-      }
-      if (prop === EVENT_ITERATOR_EVENT_META_SYMBOL) {
-        return assertedMeta;
-      }
-      return getOrBind(target, prop);
-    }
-  });
-}
-function unwrapEventIteratorEvent(container) {
-  if (!isTypescriptObject(container)) {
-    return [container, void 0];
-  }
-  const meta = container[EVENT_ITERATOR_EVENT_META_SYMBOL];
-  const target = container[EVENT_ITERATOR_EVENT_SOURCE_SYMBOL] ?? container;
-  return [target, meta];
-}
-function getEventIteratorEventMeta(container) {
-  if (!isTypescriptObject(container)) {
-    return void 0;
-  }
-  return container[EVENT_ITERATOR_EVENT_META_SYMBOL];
-}
-
-export { EVENT_ITERATOR_EVENT_META_SYMBOL, EVENT_ITERATOR_EVENT_SOURCE_SYMBOL, EventIteratorErrorEvent, EventStreamDecoder, EventStreamDecoderError, EventStreamDecoderStream, EventStreamEncoderError, assertEventStreamMessageComment, assertEventStreamMessageId, assertEventStreamMessageName, assertEventStreamMessageRetry, decodeEventStreamMessage, encodeEventStreamMessage, encodeEventStreamMessageComments, encodeEventStreamMessageData, getEventIteratorEventMeta, unwrapEventIteratorEvent, withEventIteratorEventMeta };