@openworkers/workers-types 0.1.2 → 0.1.4

package/README.md

@@ -10,6 +10,8 @@ bun add -d @openworkers/workers-types
 
 ## Usage
 
+### Exclusive mode (recommended)
+
 Add to your `tsconfig.json`:
 
 ```json
@@ -20,14 +22,33 @@ Add to your `tsconfig.json`:
 }
 ```
 
-Or use a triple-slash directive:
+This includes only OpenWorkers types and excludes conflicting types (like `@types/node` or `@types/bun`). Best for pure worker projects.
+
+### Compatible mode
+
+If you need to mix with Node.js or Bun types, just install the package without configuring `types`. The types will merge with existing globals:
+
+```json
+{
+  "compilerOptions": {
+    // no "types" array - all @types/* are included
+  }
+}
+```
+
+### Triple-slash directive
+
+For per-file control:
 
 ```typescript
+/// <reference no-default-lib="true" />
+/// <reference lib="esnext" />
 /// <reference types="@openworkers/workers-types" />
 ```
 
 ## Structure
 
+- `types/globals.d.ts` - globalThis, self
 - `types/fetch.d.ts` - Request, Response, Headers, fetch
 - `types/url.d.ts` - URL, URLSearchParams
 - `types/streams.d.ts` - ReadableStream, WritableStream

package/index.d.ts

@@ -1,5 +1,6 @@
 // OpenWorkers Runtime Types
 
+/// <reference path="./types/globals.d.ts" />
 /// <reference path="./types/events.d.ts" />
 /// <reference path="./types/abort.d.ts" />
 /// <reference path="./types/streams.d.ts" />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openworkers/workers-types",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "TypeScript types for the OpenWorkers runtime",
   "license": "MIT",
   "repository": {

package/types/abort.d.ts

@@ -1,12 +1,38 @@
 // AbortController API types
 
-interface AbortSignal extends EventTarget {
-  readonly aborted: boolean;
-  readonly reason: unknown;
-  throwIfAborted(): void;
-}
+export {};
+
+declare global {
+  /**
+   * A signal object that allows you to communicate with an async operation
+   * and abort it if required via an AbortController.
+   */
+  interface AbortSignal extends EventTarget {
+    /** Returns true if the signal has been aborted. */
+    readonly aborted: boolean;
+
+    /** The reason for aborting, if any. */
+    readonly reason: unknown;
+
+    /** Throws the abort reason if the signal has been aborted. */
+    throwIfAborted(): void;
+  }
+
+  /**
+   * A controller object that allows you to abort one or more async operations.
+   *
+   * @example
+   * ```ts
+   * const controller = new AbortController();
+   * fetch(url, { signal: controller.signal });
+   * controller.abort(); // Cancels the fetch
+   * ```
+   */
+  class AbortController {
+    /** The AbortSignal associated with this controller. */
+    readonly signal: AbortSignal;
 
-declare class AbortController {
-  readonly signal: AbortSignal;
-  abort(reason?: unknown): void;
+    /** Aborts the associated signal with an optional reason. */
+    abort(reason?: unknown): void;
+  }
 }

package/types/bindings.d.ts

@@ -1,52 +1,203 @@
 // OpenWorkers Bindings types
 
-interface BindingAssets {
-  fetch(path: string, options?: RequestInit): Promise<Response>;
-}
+export {};
 
-interface StorageHeadResult {
-  size: number;
-  etag?: string;
-}
+declare global {
+  /**
+   * Static asset binding for serving files from the worker bundle.
+   *
+   * @example
+   * ```ts
+   * export default {
+   *   async fetch(request, env) {
+   *     return env.ASSETS.fetch('/index.html');
+   *   }
+   * }
+   * ```
+   */
+  interface BindingAssets {
+    /**
+     * Fetches a static asset from the bundle.
+     * @param path The asset path (e.g., "/index.html").
+     * @param options Optional request options.
+     */
+    fetch(path: string, options?: RequestInit): Promise<Response>;
+  }
 
-interface StorageListOptions {
-  prefix?: string;
-  limit?: number;
-}
+  /**
+   * Result of a storage head operation.
+   */
+  interface StorageHeadResult {
+    /** The size of the object in bytes. */
+    size: number;
 
-interface StorageListResult {
-  keys: string[];
-  truncated: boolean;
-}
+    /** The ETag of the object, if available. */
+    etag?: string;
+  }
 
-interface BindingStorage {
-  get(key: string): Promise<string | null>;
-  put(key: string, value: string | Uint8Array): Promise<void>;
-  head(key: string): Promise<StorageHeadResult>;
-  list(options?: StorageListOptions): Promise<StorageListResult>;
-  delete(key: string): Promise<void>;
-}
+  /**
+   * Options for listing storage objects.
+   */
+  interface StorageListOptions {
+    /** Only return keys starting with this prefix. */
+    prefix?: string;
 
-interface KVPutOptions {
-  expiresIn?: number;
-}
+    /** Maximum number of keys to return. */
+    limit?: number;
+  }
 
-interface KVListOptions {
-  prefix?: string;
-  limit?: number;
-}
+  /**
+   * Result of a storage list operation.
+   */
+  interface StorageListResult {
+    /** The matching keys. */
+    keys: string[];
 
-interface BindingKV {
-  get(key: string): Promise<string | null>;
-  put(key: string, value: string, options?: KVPutOptions): Promise<void>;
-  delete(key: string): Promise<void>;
-  list(options?: KVListOptions): Promise<string[]>;
-}
+    /** Whether there are more keys beyond the limit. */
+    truncated: boolean;
+  }
 
-interface BindingDatabase {
-  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
-}
+  /**
+   * Object storage binding for storing binary data.
+   * Suitable for files, images, and large data.
+   *
+   * @example
+   * ```ts
+   * // Store data
+   * await env.STORAGE.put('file.txt', 'Hello, World!');
+   *
+   * // Retrieve data
+   * const data = await env.STORAGE.get('file.txt');
+   * ```
+   */
+  interface BindingStorage {
+    /**
+     * Retrieves a value by key.
+     * @returns The value as a string, or null if not found.
+     */
+    get(key: string): Promise<string | null>;
+
+    /**
+     * Stores a value.
+     * @param key The storage key.
+     * @param value The value to store.
+     */
+    put(key: string, value: string | Uint8Array): Promise<void>;
+
+    /**
+     * Gets metadata about an object without retrieving its contents.
+     */
+    head(key: string): Promise<StorageHeadResult>;
+
+    /**
+     * Lists keys in storage.
+     */
+    list(options?: StorageListOptions): Promise<StorageListResult>;
+
+    /**
+     * Deletes a key.
+     */
+    delete(key: string): Promise<void>;
+  }
+
+  /**
+   * Options for KV put operations.
+   */
+  interface KVPutOptions {
+    /** Time-to-live in seconds. After this time, the key expires. */
+    expiresIn?: number;
+  }
+
+  /**
+   * Options for KV list operations.
+   */
+  interface KVListOptions {
+    /** Only return keys starting with this prefix. */
+    prefix?: string;
+
+    /** Maximum number of keys to return. */
+    limit?: number;
+  }
+
+  /**
+   * Key-Value storage binding for fast, low-latency data access.
+   * Ideal for configuration, sessions, and small data.
+   *
+   * @example
+   * ```ts
+   * // Store with expiration
+   * await env.KV.put('session:abc', userData, { expiresIn: 3600 });
+   *
+   * // Retrieve
+   * const session = await env.KV.get('session:abc');
+   * ```
+   */
+  interface BindingKV {
+    /**
+     * Retrieves a value by key.
+     * @returns The value as a string, or null if not found.
+     */
+    get(key: string): Promise<string | null>;
+
+    /**
+     * Stores a value with optional expiration.
+     * @param key The storage key.
+     * @param value The value to store.
+     * @param options Optional settings like TTL.
+     */
+    put(key: string, value: string, options?: KVPutOptions): Promise<void>;
+
+    /**
+     * Deletes a key.
+     */
+    delete(key: string): Promise<void>;
+
+    /**
+     * Lists keys with optional filtering.
+     */
+    list(options?: KVListOptions): Promise<string[]>;
+  }
+
+  /**
+   * SQL database binding for relational data.
+   *
+   * @example
+   * ```ts
+   * const users = await env.DB.query<User>(
+   *   'SELECT * FROM users WHERE active = ?',
+   *   [true]
+   * );
+   * ```
+   */
+  interface BindingDatabase {
+    /**
+     * Executes a SQL query.
+     * @param sql The SQL query with ? placeholders.
+     * @param params Parameter values to bind.
+     * @returns An array of result rows.
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+  }
 
-interface BindingWorker {
-  fetch(request: Request | string, init?: RequestInit): Promise<Response>;
+  /**
+   * Service binding for calling other workers.
+   *
+   * @example
+   * ```ts
+   * const response = await env.AUTH_SERVICE.fetch(
+   *   new Request('https://internal/validate', {
+   *     method: 'POST',
+   *     body: JSON.stringify({ token })
+   *   })
+   * );
+   * ```
+   */
+  interface BindingWorker {
+    /**
+     * Calls another worker with a request.
+     * @param request The request to send.
+     * @param init Optional request options (when using string URL).
+     */
+    fetch(request: Request | string, init?: RequestInit): Promise<Response>;
+  }
 }

package/types/blob.d.ts

@@ -1,36 +1,122 @@
 // Blob & FormData API types
 
-declare class Blob {
-  constructor(
-    blobParts?: (ArrayBuffer | Uint8Array | Blob | string)[],
-    options?: { type?: string }
-  );
-  readonly size: number;
-  readonly type: string;
-  arrayBuffer(): Promise<ArrayBuffer>;
-  slice(start?: number, end?: number, contentType?: string): Blob;
-  stream(): ReadableStream<Uint8Array>;
-  text(): Promise<string>;
-}
+export {};
 
-interface File extends Blob {
-  readonly lastModified: number;
-  readonly name: string;
-}
+declare global {
+  /**
+   * A file-like object of immutable, raw data.
+   * Can be read as text, ArrayBuffer, or streamed.
+   *
+   * @example
+   * ```ts
+   * const blob = new Blob(['Hello, World!'], { type: 'text/plain' });
+   * const text = await blob.text(); // "Hello, World!"
+   * ```
+   */
+  class Blob {
+    /**
+     * Creates a new Blob.
+     * @param blobParts Array of data to include in the blob.
+     * @param options Optional settings like MIME type.
+     */
+    constructor(
+      blobParts?: (ArrayBuffer | Uint8Array | Blob | string)[],
+      options?: { type?: string }
+    );
+
+    /** The size of the blob in bytes. */
+    readonly size: number;
+
+    /** The MIME type of the blob. */
+    readonly type: string;
+
+    /** Returns a promise that resolves with an ArrayBuffer containing the blob's data. */
+    arrayBuffer(): Promise<ArrayBuffer>;
+
+    /**
+     * Returns a new Blob containing a subset of this blob's data.
+     * @param start Starting byte index (inclusive).
+     * @param end Ending byte index (exclusive).
+     * @param contentType MIME type for the new blob.
+     */
+    slice(start?: number, end?: number, contentType?: string): Blob;
+
+    /** Returns a ReadableStream for reading the blob's contents. */
+    stream(): ReadableStream<Uint8Array>;
+
+    /** Returns a promise that resolves with the blob's contents as a string. */
+    text(): Promise<string>;
+  }
+
+  /**
+   * A File is a Blob with a name and last modified timestamp.
+   * Typically obtained from FormData or file uploads.
+   */
+  interface File extends Blob {
+    /** The last modified timestamp in milliseconds since Unix epoch. */
+    readonly lastModified: number;
+
+    /** The name of the file. */
+    readonly name: string;
+  }
+
+  /**
+   * A set of key/value pairs representing form fields and their values.
+   * Used for building multipart/form-data requests.
+   *
+   * @example
+   * ```ts
+   * const form = new FormData();
+   * form.append('name', 'John');
+   * form.append('file', new Blob(['content']), 'file.txt');
+   * await fetch('/upload', { method: 'POST', body: form });
+   * ```
+   */
+  class FormData {
+    constructor();
+
+    /**
+     * Appends a new value to an existing key, or adds the key if it doesn't exist.
+     * @param name The field name.
+     * @param value The field value.
+     * @param filename Optional filename for Blob values.
+     */
+    append(name: string, value: string | Blob, filename?: string): void;
+
+    /** Deletes all values associated with a given key. */
+    delete(name: string): void;
+
+    /** Returns the first value associated with a given key. */
+    get(name: string): string | File | null;
+
+    /** Returns all values associated with a given key. */
+    getAll(name: string): (string | File)[];
+
+    /** Returns whether a given key exists. */
+    has(name: string): boolean;
+
+    /**
+     * Sets a value for a key, replacing any existing values.
+     * @param name The field name.
+     * @param value The field value.
+     * @param filename Optional filename for Blob values.
+     */
+    set(name: string, value: string | Blob, filename?: string): void;
+
+    /** Executes a callback for each key/value pair. */
+    forEach(
+      callback: (value: string | File, key: string, parent: FormData) => void
+    ): void;
+
+    /** Returns an iterator of all key/value pairs. */
+    entries(): IterableIterator<[string, string | File]>;
+
+    /** Returns an iterator of all keys. */
+    keys(): IterableIterator<string>;
+
+    /** Returns an iterator of all values. */
+    values(): IterableIterator<string | File>;
 
-declare class FormData {
-  constructor();
-  append(name: string, value: string | Blob, filename?: string): void;
-  delete(name: string): void;
-  get(name: string): string | File | null;
-  getAll(name: string): (string | File)[];
-  has(name: string): boolean;
-  set(name: string, value: string | Blob, filename?: string): void;
-  forEach(
-    callback: (value: string | File, key: string, parent: FormData) => void
-  ): void;
-  entries(): IterableIterator<[string, string | File]>;
-  keys(): IterableIterator<string>;
-  values(): IterableIterator<string | File>;
-  [Symbol.iterator](): IterableIterator<[string, string | File]>;
+    [Symbol.iterator](): IterableIterator<[string, string | File]>;
+  }
 }

package/types/console.d.ts

@@ -1,15 +1,59 @@
 // Console API types
 
-interface Console {
-  log(...args: unknown[]): void;
-  info(...args: unknown[]): void;
-  warn(...args: unknown[]): void;
-  error(...args: unknown[]): void;
-  debug(...args: unknown[]): void;
-  trace(...args: unknown[]): void;
-  time(label?: string): void;
-  timeEnd(label?: string): void;
-  timeLog(label?: string, ...args: unknown[]): void;
-}
+export {};
+
+declare global {
+  /**
+   * Provides logging functionality for debugging and diagnostics.
+   *
+   * @example
+   * ```ts
+   * console.log('Hello, World!');
+   * console.error('Something went wrong:', error);
+   * console.time('fetch');
+   * await fetch(url);
+   * console.timeEnd('fetch'); // "fetch: 123ms"
+   * ```
+   */
+  interface Console {
+    /** Outputs a message at the "log" level. */
+    log(...args: unknown[]): void;
+
+    /** Outputs a message at the "info" level. */
+    info(...args: unknown[]): void;
+
+    /** Outputs a message at the "warn" level. */
+    warn(...args: unknown[]): void;
+
+    /** Outputs a message at the "error" level. */
+    error(...args: unknown[]): void;
+
+    /** Outputs a message at the "debug" level. */
+    debug(...args: unknown[]): void;
 
-declare var console: Console;
+    /** Outputs a stack trace. */
+    trace(...args: unknown[]): void;
+
+    /**
+     * Starts a timer with the given label.
+     * @param label The timer label (default: "default").
+     */
+    time(label?: string): void;
+
+    /**
+     * Stops a timer and logs the elapsed time.
+     * @param label The timer label (default: "default").
+     */
+    timeEnd(label?: string): void;
+
+    /**
+     * Logs the current elapsed time without stopping the timer.
+     * @param label The timer label (default: "default").
+     * @param args Additional values to log.
+     */
+    timeLog(label?: string, ...args: unknown[]): void;
+  }
+
+  /** Global console object for logging. */
+  var console: Console;
+}