@dwn-protocol/id-sdk 0.2.5 → 0.2.6

package/src/common/stream.ts

@@ -1,406 +0,0 @@
-import { Convert } from './convert.js';
-
-export class Stream {
-  /**
-   * Transforms a `ReadableStream` into an `AsyncIterable`. This allows for the asynchronous
-   * iteration over the stream's data chunks.
-   *
-   * This method creates an async iterator from a `ReadableStream`, enabling the use of
-   * `for await...of` loops to process stream data. It reads from the stream until it's closed or
-   * errored, yielding each chunk as it becomes available.
-   *
-   * @example
-   * ```ts
-   * const readableStream = new ReadableStream({ ... });
-   * for await (const chunk of Stream.asAsyncIterator(readableStream)) {
-   *   // process each chunk
-   * }
-   * ```
-   *
-   * @remarks
-   * - The method ensures proper cleanup by releasing the reader lock when iteration is completed or
-   *   if an error occurs.
-   *
-   * @param readableStream - The Web `ReadableStream` to be transformed into an `AsyncIterable`.
-   * @returns An `AsyncIterable` that yields data chunks from the `ReadableStream`.
-   */
-  public static async * asAsyncIterator<T>(readableStream: ReadableStream<T>): AsyncIterable<T> {
-    const reader = readableStream.getReader();
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        yield value;
-      }
-    } finally {
-      reader.releaseLock();
-    }
-  }
-
-  /**
-   * Consumes a `ReadableStream` and returns its contents as an `ArrayBuffer`.
-   *
-   * This method reads all data from a `ReadableStream`, collects it, and converts it into an
-   * `ArrayBuffer`.
-   *
-   * @example
-   * ```ts
-   * const readableStream = new ReadableStream({ ... });
-   * const arrayBuffer = await Stream.consumeToArrayBuffer({ readableStream });
-   * ```
-   *
-   * @param readableStream - The Web `ReadableStream` whose data will be consumed.
-   * @returns A Promise that resolves to an `ArrayBuffer` containing all the data from the stream.
-   */
-  public static async consumeToArrayBuffer({ readableStream }: { readableStream: ReadableStream}): Promise<ArrayBuffer> {
-    const iterableStream = Stream.asAsyncIterator(readableStream);
-    const arrayBuffer = await Convert.asyncIterable(iterableStream).toArrayBufferAsync();
-
-    return arrayBuffer;
-  }
-
-  /**
-   * Consumes a `ReadableStream` and returns its contents as a `Blob`.
-   *
-   * This method reads all data from a `ReadableStream`, collects it, and converts it into a `Blob`.
-   *
-   * @example
-   * ```ts
-   * const readableStream = new ReadableStream({ ... });
-   * const blob = await Stream.consumeToBlob({ readableStream });
-   * ```
-   *
-   * @param readableStream - The Web `ReadableStream` whose data will be consumed.
-   * @returns A Promise that resolves to a `Blob` containing all the data from the stream.
-   */
-  public static async consumeToBlob({ readableStream }: { readableStream: ReadableStream}): Promise<Blob> {
-    const iterableStream = Stream.asAsyncIterator(readableStream);
-    const blob = await Convert.asyncIterable(iterableStream).toBlobAsync();
-
-    return blob;
-  }
-
-  /**
-   * Consumes a `ReadableStream` and returns its contents as a `Uint8Array`.
-   *
-   * This method reads all data from a `ReadableStream`, collects it, and converts it into a
-   * `Uint8Array`.
-   *
-   * @example
-   * ```ts
-   * const readableStream = new ReadableStream({ ... });
-   * const bytes = await Stream.consumeToBytes({ readableStream });
-   * ```
-   *
-   * @param readableStream - The Web `ReadableStream` whose data will be consumed.
-   * @returns A Promise that resolves to a `Uint8Array` containing all the data from the stream.
-   */
-  public static async consumeToBytes({ readableStream }: { readableStream: ReadableStream }): Promise<Uint8Array> {
-    const iterableStream = Stream.asAsyncIterator(readableStream);
-    const bytes = await Convert.asyncIterable(iterableStream).toUint8ArrayAsync();
-
-    return bytes;
-  }
-
-  /**
-   * Consumes a `ReadableStream` and parses its contents as JSON.
-   *
-   * This method reads all the data from the stream, converts it to a text string, and then parses
-   * it as JSON, returning the resulting object.
-   *
-   * @example
-   * ```ts
-   * const readableStream = new ReadableStream({ ... });
-   * const jsonData = await Stream.consumeToJson({ readableStream });
-   * ```
-   *
-   * @param readableStream - The Web `ReadableStream` whose JSON content will be consumed.
-   * @returns A Promise that resolves to the parsed JSON object from the stream's data.
-   */
-  public static async consumeToJson({ readableStream }: { readableStream: ReadableStream}): Promise<any> {
-    const iterableStream = Stream.asAsyncIterator(readableStream);
-    const object = await Convert.asyncIterable(iterableStream).toObjectAsync();
-
-    return object;
-  }
-
-  /**
-   * Consumes a `ReadableStream` and returns its contents as a text string.
-   *
-   * This method reads all the data from the stream, converting it into a single string.
-   *
-   * @example
-   * ```ts
-   * const readableStream = new ReadableStream({ ... });
-   * const text = await Stream.consumeToText({ readableStream });
-   * ```
-   *
-   * @param readableStream - The Web `ReadableStream` whose text content will be consumed.
-   * @returns A Promise that resolves to a string containing all the data from the stream.
-   */
-  public static async consumeToText({ readableStream }: { readableStream: ReadableStream}): Promise<string> {
-    const iterableStream = Stream.asAsyncIterator(readableStream);
-    const text = await Convert.asyncIterable(iterableStream).toStringAsync();
-
-    return text;
-  }
-
-  /**
-   * Generates a `ReadableStream` of `Uint8Array` chunks with customizable length and fill value.
-   *
-   * This method creates a `ReadableStream` that emits `Uint8Array` chunks. You can specify the
-   * total length of the stream, the length of individual chunks, and a fill value or range for the
-   * chunks. It's useful for testing or when specific binary data streams are required.
-   *
-   * @example
-   * ```ts
-   * // Create a stream of 1000 bytes with 100-byte chunks filled with 0xAA.
-   * const byteStream = Stream.generateByteStream({
-   *   streamLength: 1000,
-   *   chunkLength: 100,
-   *   fillValue: 0xAA
-   * });
-   *
-   * // Create an unending stream of 100KB chunks filled with values that range from 1 to 99.
-   * const byteStream = Stream.generateByteStream({
-   *  chunkLength: 100 * 1024,
-   *  fillValue: [1, 99]
-   * });
-   * ```
-   *
-   * @param streamLength - The total length of the stream in bytes. If omitted, the stream is infinite.
-   * @param chunkLength - The length of each chunk. If omitted, each chunk is the size of `streamLength`.
-   * @param fillValue - A value or range to fill the chunks with. Can be a single number or a tuple [min, max].
-   * @returns A `ReadableStream` that emits `Uint8Array` chunks.
-   */
-  public static generateByteStream({ streamLength, chunkLength, fillValue }: {
-    streamLength?: number,
-    chunkLength?: number,
-    fillValue?: number | [number, number]
-  }): ReadableStream<Uint8Array> {
-    let bytesRemaining = streamLength ?? Infinity;
-    let controller: ReadableStreamDefaultController<Uint8Array>;
-
-    function enqueueChunk() {
-      const currentChunkLength = Math.min(bytesRemaining, chunkLength ?? Infinity);
-      bytesRemaining -= currentChunkLength;
-
-      let chunk: Uint8Array;
-
-      if (typeof fillValue === 'number') {
-        chunk = new Uint8Array(currentChunkLength).fill(fillValue);
-
-      } else if (Array.isArray(fillValue)) {
-        chunk = new Uint8Array(currentChunkLength);
-        const [min, max] = fillValue;
-        const range = max - min + 1;
-        for (let i = 0; i < currentChunkLength; i++) {
-          chunk[i] = Math.floor(Math.random() * range) + min;
-        }
-
-      } else {
-        chunk = new Uint8Array(currentChunkLength);
-      }
-
-      controller.enqueue(chunk);
-
-      // If there are no more bytes to send, close the stream
-      if (bytesRemaining <= 0) {
-        controller.close();
-      }
-    }
-
-    return new ReadableStream<Uint8Array>({
-      start(c) {
-        controller = c;
-        enqueueChunk();
-      },
-      pull() {
-        enqueueChunk();
-      },
-    });
-  }
-
-  /**
-   * Checks if the provided Web `ReadableStream` is in a readable state.
-   *
-   * After verifying that the stream is a Web {@link https://streams.spec.whatwg.org/#rs-model | ReadableStream},
-   * this method checks the {@link https://streams.spec.whatwg.org/#readablestream-locked | locked}
-   * property of the ReadableStream. The `locked` property is `true` if a reader is currently
-   * active, meaning the stream is either being read or has already been read (and hence is not in a
-   * readable state). If `locked` is `false`, it means the stream is still in a state where it can
-   * be read.
-   *
-   * In the case where a `ReadableStream` has been unlocked but is no longer readable (for example,
-   * if it has been fully read or cancelled), additional checks are needed beyond just examining the
-   * locked property. The ReadableStream API does not provide a direct way to check if the stream
-   * has data left or if it's in a readable state once it's been unlocked.
-   *
-   * Per {@link https://streams.spec.whatwg.org/#other-specs-rs-introspect | WHATWG Streams, Section 9.1.3. Introspection}:
-   *
-   * > ...note that apart from checking whether or not the stream is locked, this direct
-   * > introspection is not possible via the public JavaScript API, and so specifications should
-   * > instead use the algorithms in §9.1.2 Reading. (For example, instead of testing if the stream
-   * > is readable, attempt to get a reader and handle any exception.)
-   *
-   * This implementation employs the technique suggested by the WHATWG Streams standard by
-   * attempting to acquire a reader and checking the state of the reader. If acquiring a reader
-   * succeeds, it immediately releases the lock and returns `true`, indicating the stream is
-   * readable. If an error occurs while trying to get a reader (which can happen if the stream is
-   * already closed or errored), it catches the error and returns `false`, indicating the stream is
-   * not readable.
-   *
-   * @example
-   * ```ts
-   * const readableStream = new ReadableStream({ ... });
-   * const isStreamReadable = Stream.isReadable({ readableStream });
-   * console.log(isStreamReadable); // Output: true or false
-   * ```
-   *
-   * @remarks
-   * - This method does not check whether the stream has data left to read; it only checks if the
-   *   stream is in a state that allows reading. It is possible for a stream to be unlocked but
-   *   still have no data left if it has never been locked to a reader.
-   *
-   * @param readableStream - The Web `ReadableStream` to be checked for readability.
-   *
-   * @returns `true` if the stream is a `ReadableStream` and is in a readable state (not locked and
-   *          no error on getting a reader); otherwise, `false`.
-   */
-  public static isReadable({ readableStream }: { readableStream: ReadableStream }): boolean {
-    // Check if the stream is a WHATWG `ReadableStream`.
-    if (!Stream.isReadableStream(readableStream)) {
-      return false;
-    }
-
-    // Check if the stream is locked.
-    if (readableStream.locked) {
-      return false;
-    }
-
-    try {
-      // Try to get a reader to check if the stream is readable.
-      const reader = readableStream.getReader();
-      // If successful, immediately release the lock.
-      reader.releaseLock();
-      return true;
-    } catch (error) {
-      // If an error occurs (e.g., the stream is not readable), return false.
-      return false;
-    }
-  }
-
-  /**
-   * Checks if an object is a Web `ReadableStream`.
-   *
-   * This method verifies whether the given object is a `ReadableStream` by checking its type and
-   * the presence of the `getReader` function.
-   *
-   * @example
-   * ```ts
-   * const obj = getSomeObject();
-   * if (Stream.isReadableStream(obj)) {
-   *   // obj is a ReadableStream
-   * }
-   * ```
-   *
-   * @param obj - The object to be checked.
-   * @returns `true` if `obj` is a `ReadableStream`; otherwise, `false`.
-   */
-  public static isReadableStream(obj: unknown): obj is ReadableStream {
-    return (
-      typeof obj === 'object' && obj !== null &&
-      'getReader' in obj && typeof obj.getReader === 'function'
-    );
-  }
-
-  /**
-   * Checks if an object is a Web `ReadableStream`, `WritableStream`, or `TransformStream`.
-   *
-   * This method verifies the type of a given object to determine if it is one of the standard
-   * stream types in the Web Streams API: `ReadableStream`, `WritableStream`, or `TransformStream`.
-   * It employs type-checking strategies that are specific to each stream type.
-   *
-   * The method checks for the specific functions and properties associated with each stream type:
-   * - `ReadableStream`: Identified by the presence of a `getReader` method.
-   * - `WritableStream`: Identified by the presence of a `getWriter` and `abort` methods.
-   * - `TransformStream`: Identified by having both `readable` and `writable` properties.
-   *
-   * @example
-   * ```ts
-   * const readableStream = new ReadableStream();
-   * console.log(Stream.isStream(readableStream)); // Output: true
-   *
-   * const writableStream = new WritableStream();
-   * console.log(Stream.isStream(writableStream)); // Output: true
-   *
-   * const transformStream = new TransformStream();
-   * console.log(Stream.isStream(transformStream)); // Output: true
-   *
-   * const nonStreamObject = {};
-   * console.log(Stream.isStream(nonStreamObject)); // Output: false
-   * ```
-   *
-   * @remarks
-   * - This method does not differentiate between `ReadableStream`, `WritableStream`, and
-   *   `TransformStream`. It checks if the object conforms to any of these types.
-   * - This method is specific to the Web Streams API and may not recognize non-standard or custom
-   *   stream-like objects that do not adhere to the Web Streams API specifications.
-   *
-   * @param obj - The object to be checked for being a Web `ReadableStream`, `WritableStream`, or `TransformStream`.
-   * @returns `true` if the object is a `ReadableStream`, `WritableStream`, or `TransformStream`; otherwise, `false`.
-   */
-  public static isStream(obj: unknown): obj is ReadableStream | WritableStream | TransformStream {
-    return Stream.isReadableStream(obj) || Stream.isWritableStream(obj) || Stream.isTransformStream(obj);
-  }
-
-  /**
-   * Checks if an object is a `TransformStream`.
-   *
-   * This method verifies whether the given object is a `TransformStream` by checking its type and
-   * the presence of `readable` and `writable` properties.
-   *
-   * @example
-   * ```ts
-   * const obj = getSomeObject();
-   * if (Stream.isTransformStream(obj)) {
-   *   // obj is a TransformStream
-   * }
-   * ```
-   *
-   * @param obj - The object to be checked.
-   * @returns `true` if `obj` is a `TransformStream`; otherwise, `false`.
-   */
-  public static isTransformStream(obj: unknown): obj is TransformStream {
-    return (
-      typeof obj === 'object' && obj !== null &&
-      'readable' in obj && typeof obj.readable === 'object' &&
-      'writable' in obj && typeof obj.writable === 'object'
-    );
-  }
-
-  /**
-   * Checks if an object is a `WritableStream`.
-   *
-   * This method determines whether the given object is a `WritableStream` by verifying its type and
-   * the presence of the `getWriter` and `abort` functions.
-   *
-   * @example
-   * ```ts
-   * const obj = getSomeObject();
-   * if (Stream.isWritableStream(obj)) {
-   *   // obj is a WritableStream
-   * }
-   * ```
-   *
-   * @param obj - The object to be checked.
-     * @returns `true` if `obj` is a `TransformStream`; otherwise, `false`.
-     */
-  public static isWritableStream(obj: unknown): obj is WritableStream {
-    return (
-      typeof obj === 'object' && obj !== null &&
-      'getWriter' in obj && typeof obj.getWriter === 'function' &&
-      'abort' in obj && typeof obj.abort === 'function'
-    );
-  }
-}

package/src/common/type-utils.ts

@@ -1,117 +0,0 @@
-/**
- * isArrayBufferSlice
- *
- * Checks if the ArrayBufferView represents a slice (subarray or a subview)
- * of an ArrayBuffer.
- *
- * An ArrayBufferView (TypedArray or DataView) can represent a portion of an
- * ArrayBuffer - such a view is said to be a "slice" of the original buffer.
- * This can occur when the `subarray` or `slice` method is called on a
- * TypedArray or when a DataView is created with a byteOffset and/or
- * byteLength that doesn't cover the full ArrayBuffer.
- *
- * @param arrayBufferView - The ArrayBufferView to be checked
- * @returns true if the ArrayBufferView represents a slice of an ArrayBuffer; false otherwise.
- */
-export function isArrayBufferSlice(arrayBufferView: ArrayBufferView): boolean {
-  return arrayBufferView.byteOffset !== 0 || arrayBufferView.byteLength !== arrayBufferView.buffer.byteLength;
-}
-
-/**
- * Checks if the given object is an AsyncIterable.
- *
- * An AsyncIterable is an object that implements the AsyncIterable protocol,
- * which means it has a [Symbol.asyncIterator] method. This function checks
- * if the provided object conforms to this protocol by verifying the presence
- * and type of the [Symbol.asyncIterator] method.
- *
- * @param obj - The object to be checked for AsyncIterable conformity.
- * @returns True if the object is an AsyncIterable, false otherwise.
- *
- * @example
- * ```ts
- * // Returns true for a valid AsyncIterable
- * const asyncIterable = {
- *   async *[Symbol.asyncIterator]() {
- *     yield 1;
- *     yield 2;
- *   }
- * };
- * console.log(isAsyncIterable(asyncIterable)); // true
- * ```
- *
- * @example
- * ```ts
- * // Returns false for a regular object
- * console.log(isAsyncIterable({ a: 1, b: 2 })); // false
- * ```
- */
-export function isAsyncIterable(obj: any): obj is AsyncIterable<any> {
-  if (typeof obj !== 'object' || obj === null) {
-    return false;
-  }
-
-  return typeof obj[Symbol.asyncIterator] === 'function';
-}
-
-/**
- * isDefined
- *
- * Utility function to check if a variable is neither null nor undefined.
- * This function helps in making TypeScript infer the type of the variable
- * as being defined, excluding `null` and `undefined`.
- *
- * The function uses strict equality (`!==`) for the comparison, ensuring
- * that the variable is not just falsy (like an empty string or zero),
- * but is truly either `null` or `undefined`.
- *
- * @param arg - The variable to be checked
- * @returns true if the variable is neither `null` nor `undefined`
- */
-export function isDefined<T>(arg: T): arg is Exclude<T, null | undefined> {
-  return arg !== null && typeof arg !== 'undefined';
-}
-
-/**
- * universalTypeOf
- *
- * Why does this function exist?
- *
- * You can typically check if a value is of a particular type, such as
- * Uint8Array or ArrayBuffer, by using the `instanceof` operator. The
- * `instanceof` operator checks the prototype property of a constructor
- * in the object's prototype chain.
- *
- * However, there is a caveat with the `instanceof` check if the value
- * was created from a different JavaScript context (like an iframe or
- * a web worker). In those cases, the `instanceof` check might fail
- * because each context has a different global object, and therefore,
- * different built-in constructor functions.
- *
- * The `typeof` operator provides information about the type of the
- * operand in a less detailed way. For basic data types like number,
- * string, boolean, and undefined, the `typeof` operator works as
- * expected.  However, for objects, including arrays and null,
- * it always returns "object".  For functions, it returns "function".
- * So, while `typeof` is good for basic type checking, it doesn't
- * give detailed information about complex data types.
- *
- * Unlike `instanceof` and `typeof`, `Object.prototype.toString.call(value)`
- * can ensure a consistent result across different JavaScript
- * contexts.
- *
- * Credit for inspiration:
- *   Angus Croll
- *   https://github.com/angus-c
- *   https://javascriptweblog.wordpress.com/2011/08/08/fixing-the-javascript-typeof-operator/
- */
-export function universalTypeOf(value: unknown) {
-  // Returns '[Object Type]' string.
-  const typeString = Object.prototype.toString.call(value);
-  // Returns ['Object', 'Type'] array or null.
-  const match = typeString.match(/\s([a-zA-Z0-9]+)/);
-  // Deconstructs the array and gets just the type from index 1.
-  const [_, type] = match as RegExpMatchArray;
-
-  return type;
-}

package/src/common/types.ts

@@ -1,48 +0,0 @@
-/**
- * Interface for a generic key-value store.
- */
-export interface KeyValueStore<K, V> {
-  /**
-   * Clears the store, removing all key-value pairs.
-   *
-   * @returns A promise that resolves when the store has been cleared.
-   */
-  clear(): Promise<void>;
-
-  /**
-   * Closes the store, freeing up any resources used. After calling this method, no other operations can be performed on the store.
-   *
-   * @returns A promise that resolves when the store has been closed.
-   */
-  close(): Promise<void>;
-
-  /**
-   * Deletes a key-value pair from the store.
-   *
-   * @param key - The key of the value to delete.
-   * @returns A promise that resolves to true if the element existed and has been removed, or false if the element does not exist.
-   */
-  delete(key: K): Promise<boolean | void>;
-
-  /**
-   * Fetches a value from the store given its key.
-   *
-   * @param key - The key of the value to retrieve.
-   * @returns A promise that resolves with the value associated with the key, or `undefined` if no value exists for that key.
-   */
-  get(key: K): Promise<V | undefined>;
-
-  /**
-   * Sets the value for a key in the store.
-   *
-   * @param key - The key under which to store the value.
-   * @param value - The value to be stored.
-   * @returns A promise that resolves when the value has been set.
-   */
-  set(key: K, value: V): Promise<void>;
-}
-
-/**
- * Represents an object type where a subset of keys are required and everything else is optional.
- */
-export type RequireOnly<T, K extends keyof T, O extends keyof T = never> = Required<Pick<T, K>> & Omit<Partial<T>, O>;