wrangler 0.0.0-e22f9d7 → 0.0.0-e273e09

package/src/{kv.tsx → kv.ts}

@@ -1,13 +1,18 @@
 import { URLSearchParams } from "node:url";
+import { fetchListResult, fetchResult, fetchKVGetValue } from "./cfetch";
+import { logger } from "./logger";
 import type { Config } from "./config";
-import { fetchListResult, fetchResult } from "./cfetch";
+
+/** The largest number of kv items we can pass to the API in a single request. */
+const API_MAX = 10000;
+// The const below are halved from the API's true capacity to help avoid
+// hammering it with large requests.
+const BATCH_KEY_MAX = API_MAX / 2;
 
 type KvArgs = {
   binding?: string;
   "namespace-id"?: string;
-  env?: string;
   preview?: boolean;
-  config?: Config;
 };
 
 /**
@@ -15,7 +20,7 @@ type KvArgs = {
  *
  * @returns the generated id of the created namespace.
  */
-export async function createNamespace(
+export async function createKVNamespace(
   accountId: string,
   title: string
 ): Promise<string> {
@@ -47,7 +52,7 @@ export interface KVNamespaceInfo {
 /**
  * Fetch a list of all the namespaces under the given `accountId`.
  */
-export async function listNamespaces(
+export async function listKVNamespaces(
   accountId: string
 ): Promise<KVNamespaceInfo[]> {
   const pageSize = 100;
@@ -79,7 +84,7 @@ export interface NamespaceKeyInfo {
   metadata?: { [key: string]: unknown };
 }
 
-export async function listNamespaceKeys(
+export async function listKVNamespaceKeys(
   accountId: string,
   namespaceId: string,
   prefix = ""
@@ -91,67 +96,218 @@ export async function listNamespaceKeys(
   );
 }
 
-export async function putKeyValue(
+export async function deleteKVNamespace(
+  accountId: string,
+  namespaceId: string
+) {
+  return await fetchResult<{ id: string }>(
+    `/accounts/${accountId}/storage/kv/namespaces/${namespaceId}`,
+    { method: "DELETE" }
+  );
+}
+
+/**
+ * Information about a key-value pair, including its "metadata" fields.
+ */
+export interface KeyValue {
+  key: string;
+  value: string;
+  expiration?: number;
+  expiration_ttl?: number;
+  metadata?: object;
+  base64?: boolean;
+}
+
+const KeyValueKeys = new Set([
+  "key",
+  "value",
+  "expiration",
+  "expiration_ttl",
+  "metadata",
+  "base64",
+]);
+
+/**
+ * The object has the specified property.
+ */
+function hasProperty<T extends object>(
+  obj: object,
+  property: keyof T
+): obj is T {
+  return property in obj;
+}
+
+/**
+ * The object has a required property of the specified type.
+ */
+function hasTypedProperty<T extends object>(
+  obj: object,
+  property: keyof T,
+  type: string
+): obj is T {
+  return hasProperty(obj, property) && typeof obj[property] === type;
+}
+
+/**
+ * The object an optional property, of the specified type.
+ */
+function hasOptionalTypedProperty<T extends object>(
+  obj: object,
+  property: keyof T,
+  type: string
+): obj is Omit<T, typeof property> | T {
+  return !hasProperty(obj, property) || typeof obj[property] === type;
+}
+
+/**
+ * Is the given object a valid `KeyValue` type?
+ */
+export function isKVKeyValue(keyValue: unknown): keyValue is KeyValue {
+  if (
+    keyValue === null ||
+    typeof keyValue !== "object" ||
+    !hasTypedProperty(keyValue, "key", "string") ||
+    !hasTypedProperty(keyValue, "value", "string") ||
+    !hasOptionalTypedProperty(keyValue, "expiration", "number") ||
+    !hasOptionalTypedProperty(keyValue, "expiration_ttl", "number") ||
+    !hasOptionalTypedProperty(keyValue, "base64", "boolean") ||
+    !hasOptionalTypedProperty(keyValue, "metadata", "object")
+  ) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Get all the properties on the `keyValue` that are not expected.
+ */
+export function unexpectedKVKeyValueProps(keyValue: KeyValue): string[] {
+  const props = Object.keys(keyValue);
+  return props.filter((prop) => !KeyValueKeys.has(prop));
+}
+
+export async function putKVKeyValue(
   accountId: string,
   namespaceId: string,
-  key: string,
-  value: string,
-  args?: { expiration?: number; expiration_ttl?: number }
+  keyValue: KeyValue
 ) {
   let searchParams: URLSearchParams | undefined;
-  if (args) {
+  if (keyValue.expiration || keyValue.expiration_ttl) {
     searchParams = new URLSearchParams();
-    if (args.expiration) {
-      searchParams.set("expiration", `${args.expiration}`);
+    if (keyValue.expiration) {
+      searchParams.set("expiration", `${keyValue.expiration}`);
     }
-    if (args.expiration_ttl) {
-      searchParams.set("expiration_ttl", `${args.expiration_ttl}`);
+    if (keyValue.expiration_ttl) {
+      searchParams.set("expiration_ttl", `${keyValue.expiration_ttl}`);
     }
   }
   return await fetchResult(
-    `/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/values/${key}`,
-    { method: "PUT", body: value },
+    `/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/values/${encodeURIComponent(
+      keyValue.key
+    )}`,
+    { method: "PUT", body: keyValue.value },
     searchParams
   );
 }
 
-export async function putBulkKeyValue(
+export async function getKVKeyValue(
+  accountId: string,
+  namespaceId: string,
+  key: string
+): Promise<string> {
+  return await fetchKVGetValue(accountId, namespaceId, encodeURIComponent(key));
+}
+
+export async function deleteKVKeyValue(
   accountId: string,
   namespaceId: string,
-  keyvalueStr: string
+  key: string
 ) {
   return await fetchResult(
-    `/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/bulk`,
-    {
-      method: "PUT",
-      body: keyvalueStr,
-      headers: { "Content-Type": "application/json" },
-    }
+    `/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/values/${encodeURIComponent(
+      key
+    )}`,
+    { method: "DELETE" }
+  );
+}
+
+/**
+ * Formatter for converting e.g. 5328 --> 5,328
+ */
+const formatNumber = new Intl.NumberFormat("en-US", {
+  notation: "standard",
+}).format;
+
+/**
+ * Helper function for bulk requests, logs ongoing output to console.
+ */
+function logBulkProgress(
+  operation: "put" | "delete",
+  index: number,
+  total: number
+) {
+  logger.log(
+    `${operation === "put" ? "Uploaded" : "Deleted"} ${Math.floor(
+      (100 * index) / total
+    )}% (${formatNumber(index)} out of ${formatNumber(total)})`
   );
 }
 
-export async function deleteBulkKeyValue(
+export async function putKVBulkKeyValue(
   accountId: string,
   namespaceId: string,
-  keyStr: string
+  keyValues: KeyValue[],
+  quiet = false
 ) {
-  return await fetchResult(
-    `/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/bulk`,
-    {
-      method: "DELETE",
-      body: keyStr,
-      headers: { "Content-Type": "application/json" },
+  for (let index = 0; index < keyValues.length; index += BATCH_KEY_MAX) {
+    if (!quiet && keyValues.length > BATCH_KEY_MAX) {
+      logBulkProgress("put", index, keyValues.length);
     }
-  );
+
+    await fetchResult(
+      `/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/bulk`,
+      {
+        method: "PUT",
+        body: JSON.stringify(keyValues.slice(index, index + BATCH_KEY_MAX)),
+        headers: { "Content-Type": "application/json" },
+      }
+    );
+  }
+
+  if (!quiet && keyValues.length > BATCH_KEY_MAX) {
+    logBulkProgress("put", keyValues.length, keyValues.length);
+  }
+}
+
+export async function deleteKVBulkKeyValue(
+  accountId: string,
+  namespaceId: string,
+  keys: string[],
+  quiet = false
+) {
+  for (let index = 0; index < keys.length; index += BATCH_KEY_MAX) {
+    if (!quiet && keys.length > BATCH_KEY_MAX) {
+      logBulkProgress("delete", index, keys.length);
+    }
+
+    await fetchResult(
+      `/accounts/${accountId}/storage/kv/namespaces/${namespaceId}/bulk`,
+      {
+        method: "DELETE",
+        body: JSON.stringify(keys.slice(index, index + BATCH_KEY_MAX)),
+        headers: { "Content-Type": "application/json" },
+      }
+    );
+  }
+  if (!quiet && keys.length > BATCH_KEY_MAX) {
+    logBulkProgress("delete", keys.length, keys.length);
+  }
 }
 
-export function getNamespaceId({
-  preview,
-  binding,
-  config,
-  "namespace-id": namespaceId,
-  env,
-}: KvArgs): string {
+export function getKVNamespaceId(
+  { preview, binding, "namespace-id": namespaceId }: KvArgs,
+  config: Config
+): string {
   // nice
   if (namespaceId) {
     return namespaceId;
@@ -159,7 +315,7 @@ export function getNamespaceId({
 
   // begin pre-flight checks
 
-  // `--binding` is only valid if there's a wrangler configuration file.
+  // `--binding` is only valid if there's a wrangler configuration.
   if (binding && !config) {
     throw new Error("--binding specified, but no config file was found.");
   }
@@ -172,30 +328,6 @@ export function getNamespaceId({
     );
   }
 
-  // they want to use an environment, actually
-  if (env) {
-    if (!config.env || !config.env[env]) {
-      throw new Error(
-        `Failed to find environment "${env}" in configuration file!`
-      );
-    }
-
-    // TODO: either a bespoke arg type for this function to avoid `undefined`s or an `EnvOrConfig` type
-    return getNamespaceId({
-      binding,
-      "namespace-id": namespaceId,
-      env: undefined,
-      preview,
-      config: {
-        env: undefined,
-        build: undefined,
-        name: undefined,
-        account_id: undefined,
-        ...config.env[env],
-      },
-    });
-  }
-
   // there's no KV namespaces
   if (!config.kv_namespaces || config.kv_namespaces.length === 0) {
     throw new Error(
@@ -267,7 +399,7 @@ export function getNamespaceId({
 /**
  * KV namespace binding names must be valid JS identifiers.
  */
-export function isValidNamespaceBinding(
+export function isValidKVNamespaceBinding(
   binding: string | undefined
 ): binding is string {
   return (

package/src/logger.ts

@@ -0,0 +1,66 @@
+import { format } from "node:util";
+import { formatMessagesSync } from "esbuild";
+
+const LOGGER_LEVELS = {
+  error: 0,
+  warn: 1,
+  log: 2,
+  debug: 3,
+} as const;
+
+type LoggerLevel = keyof typeof LOGGER_LEVELS;
+
+/** A map from LOGGER_LEVEL to the error `kind` needed by `formatMessagesSync()`. */
+const LOGGER_LEVEL_FORMAT_TYPE_MAP = {
+  error: "error",
+  warn: "warning",
+  log: undefined,
+  debug: undefined,
+} as const;
+
+class Logger {
+  constructor(public loggerLevel: LoggerLevel = "log") {}
+
+  columns = process.stdout.columns;
+
+  debug = (...args: unknown[]) => this.doLog("debug", args);
+  log = (...args: unknown[]) => this.doLog("log", args);
+  warn = (...args: unknown[]) => this.doLog("warn", args);
+  error = (...args: unknown[]) => this.doLog("error", args);
+
+  private doLog(messageLevel: LoggerLevel, args: unknown[]) {
+    if (LOGGER_LEVELS[this.loggerLevel] >= LOGGER_LEVELS[messageLevel]) {
+      console[messageLevel](this.formatMessage(messageLevel, format(...args)));
+    }
+  }
+
+  private formatMessage(level: LoggerLevel, message: string): string {
+    const kind = LOGGER_LEVEL_FORMAT_TYPE_MAP[level];
+    if (kind) {
+      // Format the message using the esbuild formatter.
+      // The first line of the message is the main `text`,
+      // subsequent lines are put into the `notes`.
+      const [firstLine, ...otherLines] = message.split("\n");
+      const notes =
+        otherLines.length > 0
+          ? otherLines.map((text) => ({ text }))
+          : undefined;
+      return formatMessagesSync([{ text: firstLine, notes }], {
+        color: true,
+        kind,
+        terminalWidth: this.columns,
+      })[0];
+    } else {
+      return message;
+    }
+  }
+}
+
+/**
+ * A drop-in replacement for `console` for outputting logging messages.
+ *
+ * Errors and Warnings will get additional formatting to highlight them to the user.
+ * You can also set a `logger.loggerLevel` value to one of "debug", "log", "warn" or "error",
+ * to filter out logging messages.
+ */
+export const logger = new Logger();

package/src/miniflare-cli/README.md

@@ -0,0 +1,30 @@
+# Custom Miniflare CLI
+
+This directory contains a simple wrapper around the programmatic Miniflare API,
+which Wrangler spawns when running `wrangler dev` in local mode.
+
+## Building
+
+This CLI is built at the same time as Wrangler by running
+
+```
+npm run -w wrangler build
+```
+
+The output of the build is `miniflare-dist/index.mjs`.
+
+## Running
+
+The CLI expects a single command line argument which is the Miniflare options formatted as a string of JSON.
+
+```bash
+node --no-warnings ./packages/wrangler/miniflare-dist/index.mjs '{"watch": true, "script": ""}' --log VERBOSE
+```
+
+The `--log` argument is optional and takes one of Miniflare's LogLevels: "NONE", "ERROR", "WARN", "INFO", "DEBUG", "VERBOSE".
+It defaults to `INFO`.
+
+## Debugging
+
+Simply place a breakpoint in the code and run the above command in the VS Code "JavaScript Debug Terminal".
+The code will stop at the breakpoint as expected.

package/src/miniflare-cli/enum-keys.ts

@@ -0,0 +1,17 @@
+export type EnumKeys<Enum> = Exclude<keyof Enum, number>;
+
+export const enumObject = <Enum extends Record<string, number | string>>(
+  e: Enum
+) => {
+  const copy = { ...e } as { [K in EnumKeys<Enum>]: Enum[K] };
+  Object.values(e).forEach(
+    (value) => typeof value === "number" && delete copy[value]
+  );
+  return copy;
+};
+
+export const enumKeys = <Enum extends Record<string, number | string>>(
+  e: Enum
+) => {
+  return Object.keys(enumObject(e)) as EnumKeys<Enum>[];
+};

package/src/miniflare-cli/index.ts

@@ -0,0 +1,41 @@
+import { Log, LogLevel, Miniflare } from "miniflare";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { enumKeys } from "./enum-keys";
+import { getRequestContextCheckOptions } from "./request-context";
+
+async function main() {
+  const args = await yargs(hideBin(process.argv))
+    .help(false)
+    .version(false)
+    .option("log", {
+      choices: enumKeys(LogLevel),
+    }).argv;
+
+  const logLevel = LogLevel[args.log ?? "INFO"];
+  const requestContextCheckOptions = await getRequestContextCheckOptions();
+  const config = {
+    ...JSON.parse((args._[0] as string) ?? "{}"),
+    ...requestContextCheckOptions,
+    log: new Log(logLevel),
+  };
+
+  if (logLevel > LogLevel.INFO) {
+    console.log("OPTIONS:\n", JSON.stringify(config, null, 2));
+  }
+
+  const mf = new Miniflare(config);
+
+  try {
+    // Start Miniflare development server
+    await mf.startServer();
+    await mf.startScheduler();
+  } catch (e) {
+    mf.log.error(e as Error);
+    process.exitCode = 1;
+    // Unmount any mounted workers
+    await mf.dispose();
+  }
+}
+
+await main();

package/src/miniflare-cli/request-context.ts

@@ -0,0 +1,40 @@
+import type { MiniflareOptions } from "miniflare";
+
+/**
+ * Certain runtime APIs are only available to workers during the "request context",
+ * which is any code that returns after receiving a request and before returning
+ * a response.
+ *
+ * Miniflare emulates this behavior by using an [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) and
+ * [checking at runtime](https://github.com/cloudflare/miniflare/blob/master/packages/shared/src/context.ts#L21-L36)
+ * to see if you're using those APIs during the request context.
+ *
+ * In certain environments `AsyncLocalStorage` is unavailable, such as in a
+ * [webcontainer](https://github.com/stackblitz/webcontainer-core).
+ * This function figures out if we're able to run those "request context" checks
+ * and returns [a set of options](https://miniflare.dev/core/standards#global-functionality-limits)
+ * that indicate to miniflare whether to run the checks or not.
+ */
+export const getRequestContextCheckOptions = async (): Promise<
+  Pick<MiniflareOptions, "globalAsyncIO" | "globalTimers" | "globalRandom">
+> => {
+  // check that there's an implementation of AsyncLocalStorage
+  let hasAsyncLocalStorage = true;
+  try {
+    // ripped from  the example here https://nodejs.org/api/async_context.html#class-asynclocalstorage
+    const { AsyncLocalStorage } = await import("node:async_hooks");
+    const storage = new AsyncLocalStorage<string>();
+
+    hasAsyncLocalStorage = storage.run("some-value", () => {
+      return storage.getStore() === "some-value";
+    });
+  } catch (e) {
+    hasAsyncLocalStorage = false;
+  }
+
+  return {
+    globalAsyncIO: hasAsyncLocalStorage,
+    globalRandom: hasAsyncLocalStorage,
+    globalTimers: hasAsyncLocalStorage,
+  };
+};