@jundle/cloudflare 0.0.0-stage → 0.0.1-0

package/src/index.d.ts

@@ -0,0 +1,389 @@
+// Type declarations for @jundle/cloudflare — the Cloudflare Workers
+// runtime for the jundle dev server (SPEC §16.3, §16.2, §16.11).
+//
+// The module is a runtime plugin: it exports { createRunner,
+// defaultOptions } directly, plus the same object as the default
+// export. The dev server loads it through loadRuntimePlugin and
+// talks to the returned runner only through the SPEC §16.2 runner
+// interface (fetch / invalidate / dispose, plus optional start);
+// the extra methods on the runner (startScript, dispatchFetch,
+// setScript, dispatchScheduled, getQueueProducer) are the
+// standalone/test path and are not part of that interface.
+//
+// The SPEC §16.2 core (InvalidatedModule, InvalidateOptions, the
+// fetch/invalidate/dispose/start shape) is intentionally
+// duplicated per runtime package — there is no shared package to
+// import it from, and these two runtimes must not cross-import.
+//
+// No `any` is used anywhere in this file. Two types are structural
+// by necessity, not by choice:
+// - WranglerConfig / CloudflareRunnerMiniflareOptions are
+//   hand-written from the fields this package actually reads and
+//   builds (wrangler's config in config.js, the Miniflare mapping
+//   in bindings.js). They are NOT imported from "wrangler" or
+//   "miniflare": miniflare 4.20260730.0's shipped declarations do
+//   not resolve in this workspace (they import
+//   @cloudflare/workers-types, ./core and ./shared, none of which
+//   are installed), and wrangler's declarations pull miniflare's
+//   in, so importing either breaks typechecking for any consumer
+//   without skipLibCheck. The structural types below cover every
+//   field this package reads or builds; WranglerConfig carries an
+//   index signature so other wrangler fields remain readable (as
+//   unknown) instead of erroring.
+// - CloudflareRunner.startScript returns the underlying Miniflare
+//   instance, typed as unknown for the same reason.
+
+/** One invalidated module, as the dev server reports it (SPEC §16.2). */
+export interface InvalidatedModule {
+  /** Graph name the module belongs to. */
+  env: string;
+  /** Absolute path of the invalidated file. */
+  file: string;
+}
+
+/** A class export of the dev entry, as discovered by the dev server's
+ * static analysis (SPEC §16.11). Only classes directly extending a
+ * cloudflare:workers import are detected; only non-static,
+ * non-computed instance methods are delegated to the wrapper. */
+export interface ExportShapeClass {
+  /** Exported name of the class. */
+  name: string;
+  /** Which Workers base class it extends. */
+  kind: "durable-object" | "workflow" | "entrypoint";
+  /** Instance method names delegated by the generated wrapper. */
+  methods: string[];
+}
+
+/**
+ * The dev entry's export shape, as produced by the dev server's
+ * discoverEntryExports (SPEC §16.11). The runner only reads
+ * `classes` (to generate the static harness wrappers); `chain` is
+ * the server's own bookkeeping — the canonical files in the entry's
+ * re-export chain, used to re-run discovery — and is ignored here.
+ */
+export interface ExportShape {
+  classes: ExportShapeClass[];
+  chain?: Set<string>;
+}
+
+/** Options passed to a runner's `invalidate` (SPEC §16.2). */
+export interface InvalidateOptions {
+  /**
+   * A changed export shape. Present only when the server detected
+   * an export-shape change; the runner rebuilds Miniflare with new
+   * wrappers. Absent on an ordinary file change, where invalidate
+   * is a no-op (the harness pulls the recorded batch via the version
+   * route on next dispatch).
+   */
+  exportShape?: ExportShape;
+}
+
+/**
+ * Entry options for this runtime, opaque to jundle core (SPEC
+ * §16.2): the dev entry's `options` object, passed to createRunner
+ * untouched. Only the keys below are read.
+ */
+export interface CloudflareRunnerOptions {
+  /**
+   * Path to the wrangler config file, resolved against configDir.
+   * Defaults to null, which auto-discovers wrangler.jsonc,
+   * wrangler.json, then wrangler.toml in the config directory.
+   */
+  wranglerConfig?: string | null;
+  /**
+   * Names of bindings to serve remotely (via the deployed remote
+   * proxy Worker) instead of locally. Each name must be a binding
+   * in the wrangler file. AI / Browser Rendering / Vectorize
+   * bindings are always remote and need not be listed.
+   */
+  remoteBindings?: string[];
+  /**
+   * Local service-binding targets ({ name: script }): extra workers
+   * run alongside the main worker via Miniflare's `workers` array
+   * (CF-3 multi-worker). Scripts are ESM source text.
+   */
+  serviceWorkers?: Record<string, string>;
+}
+
+/** A D1 migration entry kept on the runner options (not a Miniflare
+ * option — wrangler dev applies migrations itself, so the runner
+ * applies them against the started instance; see bindings.js). */
+export interface D1Migration {
+  /** Binding name of the D1 database. */
+  binding: string;
+  /** Absolute directory holding the .sql migration files. */
+  dir: string;
+}
+
+/** A remote binding reference: the binding is served through the
+ * deployed remote proxy Worker. Only present when a proxy URL is
+ * configured (CLOUDFLARE_REMOTE_PROXY_URL); the runner throws
+ * otherwise, never silently falling back to local. */
+export interface RemoteBindingRef {
+  remoteProxyConnectionString: string;
+}
+
+/**
+ * The Miniflare options the runner was built with, as produced by
+ * wranglerToMiniflareOptions (bindings.js) from the wrangler file.
+ * Every binding is wired; nothing is silently stubbed. Persistence
+ * mirrors wrangler dev (.wrangler/state/v3 under the project root).
+ */
+export interface CloudflareRunnerMiniflareOptions {
+  modules: true;
+  /** Main Worker's name, from the wrangler config. */
+  name?: string;
+  compatibilityDate?: string;
+  compatibilityFlags?: string[];
+  /** Plain bindings: wrangler `vars` overlaid with `.dev.vars`. */
+  bindings: Record<string, string>;
+  /** Set only when a remote binding is in use. */
+  cloudflareAccountId?: string;
+  /** Set only when a remote binding is in use. */
+  cloudflareApiToken?: string;
+  kvNamespaces?: string[] | Record<string, string | ({ id?: string } & RemoteBindingRef)>;
+  kvPersist?: string;
+  r2Buckets?: string[] | Record<string, string | ({ id: string } & RemoteBindingRef)>;
+  r2Persist?: string;
+  d1Databases?: Record<string, string | ({ id: string } & RemoteBindingRef)>;
+  d1Persist?: string;
+  /** Kept for the runner to apply; not a Miniflare option. */
+  d1Migrations?: D1Migration[];
+  durableObjects?: Record<string, string | ({ className: string } & Partial<RemoteBindingRef>)>;
+  durableObjectsPersist?: string;
+  queueProducers?: Record<string, string | ({ queueName: string } & Partial<RemoteBindingRef>)>;
+  queueConsumers?: Record<
+    string,
+    {
+      maxBatchSize?: number;
+      maxBatchTimeout?: number;
+      maxRetries?: number;
+      deadLetterQueue?: string;
+    }
+  >;
+  workflows?: Record<string, { name: string; className: string } & Partial<RemoteBindingRef>>;
+  workflowsPersist?: string;
+  /** Cron triggers, from wrangler `triggers.crons`. */
+  crons?: string[];
+  serviceBindings?: Record<string, string>;
+  assets?: {
+    directory: string;
+    routerConfig: { has_user_worker: boolean };
+  };
+  ai?: { binding: string } & RemoteBindingRef;
+  browserRendering?: { binding: string } & RemoteBindingRef;
+  vectorize?: Record<string, { index_name: string } & RemoteBindingRef>;
+}
+
+/**
+ * The wrangler config object returned by wrangler's
+ * unstable_readConfig, as this package reads it. Only the fields
+ * this package uses are typed precisely; any other wrangler field
+ * is readable through the index signature as `unknown`. See the
+ * header note for why this is structural instead of imported from
+ * "wrangler".
+ */
+export interface WranglerConfig {
+  name?: string;
+  compatibility_date?: string;
+  compatibility_flags?: string[];
+  /** Plain `vars` (string bindings) from the wrangler file. */
+  vars?: Record<string, string>;
+  kv_namespaces?: Array<{
+    binding: string;
+    id?: string;
+    preview_id?: string;
+    remote?: boolean;
+  }>;
+  r2_buckets?: Array<{
+    binding: string;
+    bucket_name?: string;
+    preview_bucket_name?: string;
+    jurisdiction?: string;
+  }>;
+  d1_databases?: Array<{
+    binding: string;
+    database_name?: string;
+    database_id?: string;
+    preview_database_id?: string;
+    migrations_dir?: string;
+    migrations_table?: string;
+  }>;
+  durable_objects?: {
+    bindings?: Array<{
+      name: string;
+      class_name: string;
+      script_name?: string;
+    }>;
+  };
+  queues?: {
+    producers?: Array<{
+      binding: string;
+      queue: string;
+      delivery_delay?: number;
+      remote?: boolean;
+    }>;
+    consumers?: Array<{
+      queue: string;
+      max_batch_size?: number;
+      max_batch_timeout?: number;
+      max_retries?: number;
+      dead_letter_queue?: string;
+    }>;
+  };
+  workflows?: Array<{
+    binding: string;
+    name: string;
+    class_name: string;
+  }>;
+  triggers?: {
+    crons?: string[];
+  };
+  services?: Array<{
+    binding: string;
+    service: string;
+    environment?: string;
+  }>;
+  /** A plain path string, or an object with a `directory`. */
+  assets?: string | { directory?: string };
+  ai?: {
+    binding: string;
+    staging?: boolean;
+    remote?: boolean;
+  };
+  browser?: {
+    binding: string;
+  };
+  vectorize?: Array<{
+    binding: string;
+    index_name?: string;
+  }>;
+  [key: string]: unknown;
+}
+
+/** Result of dispatching a scheduled event (cf-plugin-cf3.test.js
+ * asserts `outcome === "ok"`). */
+export interface ScheduledDispatchResult {
+  outcome: string;
+}
+
+/** Options for sending a message through a Queue producer binding. */
+export interface QueueSendOptions {
+  contentType?: "text" | "json" | "bytes" | "v8";
+  delaySeconds?: number;
+}
+
+/**
+ * A Queue producer binding, as returned by
+ * {@link CloudflareRunner.getQueueProducer}. The producer sends to
+ * the real queue; the consumer Worker's queue() handler runs on
+ * delivery. `send` is exercised by the repo's tests;
+ * `sendBatch` is the other half of the Workers Queue producer
+ * surface.
+ */
+export interface QueueProducer<Body = unknown> {
+  send(message: Body, options?: QueueSendOptions): Promise<void>;
+  sendBatch(batch: Iterable<{ body: Body } & QueueSendOptions>): Promise<void>;
+}
+
+/**
+ * The runner returned by {@link createRunner}. The first group is
+ * the SPEC §16.2 runner interface the dev server uses; the second
+ * group is plugin-specific (standalone/test path, not part of the
+ * interface). `config`, `wranglerFile` and `options` are the
+ * resolved wrangler state, exposed for inspection.
+ */
+export interface CloudflareRunner {
+  /** Parsed wrangler config (see {@link WranglerConfig}). */
+  config: WranglerConfig;
+  /** Absolute path of the wrangler config file that was read. */
+  wranglerFile: string;
+  /** Miniflare options built from the wrangler config. */
+  options: CloudflareRunnerMiniflareOptions;
+
+  /** Dispatch an app request to the entry's app. Throws if the
+   * runner has not been started. */
+  fetch(request: Request): Promise<Response>;
+  /**
+   * File-change signal. A no-op unless `opts.exportShape` is
+   * present, in which case Miniflare is rebuilt with new wrappers
+   * (built before the old instance is disposed) and the
+   * reconstruction is logged. Throws if called before start with
+   * an export shape.
+   */
+  invalidate(invalidated: InvalidatedModule[], opts?: InvalidateOptions): Promise<void>;
+  /**
+   * Start the harness worker, once the dev server has bound (it
+   * needs the base URL to fetch dev modules). Re-starting disposes
+   * the previous Miniflare instance first.
+   */
+  start(options: { baseUrl: string }): Promise<void>;
+  /** Dispose the Miniflare instance, if any. Safe to call twice. */
+  dispose(): Promise<void>;
+
+  /**
+   * Standalone/test path: start Miniflare with a given script (no
+   * harness). Not part of the runner interface. Returns the
+   * underlying Miniflare instance (typed as unknown — see the
+   * header note).
+   */
+  startScript(script: string): Promise<unknown>;
+  /**
+   * Dispatch a fetch by plain values, not a Request object
+   * (Miniflare's dispatchFetch does a cross-realm instanceof check
+   * that Node's Request fails). Throws if not started.
+   */
+  dispatchFetch(url: string, init?: RequestInit): Promise<Response>;
+  /** Replace the running worker's script. Throws if not started. */
+  setScript(script: string): Promise<void>;
+  /**
+   * Trigger the Worker's scheduled handler with a cron expression
+   * (empty string when omitted). Throws if not started.
+   */
+  dispatchScheduled(cron?: string): Promise<ScheduledDispatchResult>;
+  /**
+   * Return the Queue producer for a binding, so the caller can
+   * send; the consumer runs automatically on delivery. Throws if
+   * not started.
+   */
+  getQueueProducer(binding: string): Promise<QueueProducer>;
+}
+
+/** Arguments to {@link createRunner}. */
+export interface CreateCloudflareRunnerArgs {
+  /** Project root: the wrangler file is resolved against this. */
+  configDir: string;
+  /** Dev URL of the entry module, fetched by the harness. */
+  entryUrl: string;
+  /**
+   * The entry's export shape from the server's static analysis
+   * (SPEC §16.11). Tolerated when absent — the harness is then
+   * built with no class wrappers.
+   */
+  exportShape?: ExportShape | null;
+  /** This runtime's entry options (see {@link CloudflareRunnerOptions}). */
+  options?: CloudflareRunnerOptions;
+}
+
+/**
+ * Create the Cloudflare Workers runner for a dev entry. Reads the
+ * wrangler config (via wrangler's unstable_readConfig) and maps it
+ * to Miniflare options; the Miniflare instance itself is not
+ * started until {@link CloudflareRunner.start} (the harness needs
+ * the dev server's bound base URL). Throws when no wrangler file
+ * is found, when remote bindings lack credentials or a proxy URL,
+ * or when `remoteBindings` names an unknown binding.
+ */
+export declare function createRunner(args: CreateCloudflareRunnerArgs): Promise<CloudflareRunner>;
+
+/** Default entry options: wrangler config auto-discovery. */
+export declare const defaultOptions: CloudflareRunnerOptions;
+
+/** The runtime plugin shape (SPEC §16.2): a single runtime. */
+export interface CloudflareRuntimePlugin {
+  createRunner: typeof createRunner;
+  defaultOptions: CloudflareRunnerOptions;
+}
+
+declare const _default: CloudflareRuntimePlugin;
+export default _default;