@hexclave/shared 1.0.2 → 1.0.5

package/src/utils/dates.tsx

@@ -0,0 +1,246 @@
+import { intervalSchema } from "../schema-fields";
+import { HexclaveAssertionError } from "./errors";
+import { remainder } from "./math";
+
+export function isWeekend(date: Date): boolean {
+  return date.getDay() === 0 || date.getDay() === 6;
+}
+
+import.meta.vitest?.test("isWeekend", ({ expect }) => {
+  // Sunday (day 0)
+  expect(isWeekend(new Date(2023, 0, 1))).toBe(true);
+  // Saturday (day 6)
+  expect(isWeekend(new Date(2023, 0, 7))).toBe(true);
+  // Monday (day 1)
+  expect(isWeekend(new Date(2023, 0, 2))).toBe(false);
+  // Friday (day 5)
+  expect(isWeekend(new Date(2023, 0, 6))).toBe(false);
+});
+
+const agoUnits = [
+  [60, 'second'],
+  [60, 'minute'],
+  [24, 'hour'],
+  [7, 'day'],
+  [5, 'week'],
+] as const;
+
+export function fromNow(date: Date): string {
+  return fromNowDetailed(date).result;
+}
+
+import.meta.vitest?.test("fromNow", ({ expect }) => {
+  // Set a fixed date for testing
+  const fixedDate = new Date("2023-01-15T12:00:00.000Z");
+
+  // Use Vitest's fake timers
+  import.meta.vitest?.vi.useFakeTimers();
+  import.meta.vitest?.vi.setSystemTime(fixedDate);
+
+  // Test past times
+  expect(fromNow(new Date("2023-01-15T11:59:50.000Z"))).toBe("just now");
+  expect(fromNow(new Date("2023-01-15T11:59:00.000Z"))).toBe("1 minute ago");
+  expect(fromNow(new Date("2023-01-15T11:00:00.000Z"))).toBe("1 hour ago");
+  expect(fromNow(new Date("2023-01-14T12:00:00.000Z"))).toBe("1 day ago");
+  expect(fromNow(new Date("2023-01-08T12:00:00.000Z"))).toBe("1 week ago");
+
+  // Test future times
+  expect(fromNow(new Date("2023-01-15T12:00:10.000Z"))).toBe("just now");
+  expect(fromNow(new Date("2023-01-15T12:01:00.000Z"))).toBe("in 1 minute");
+  expect(fromNow(new Date("2023-01-15T13:00:00.000Z"))).toBe("in 1 hour");
+  expect(fromNow(new Date("2023-01-16T12:00:00.000Z"))).toBe("in 1 day");
+  expect(fromNow(new Date("2023-01-22T12:00:00.000Z"))).toBe("in 1 week");
+
+  // Test very old dates (should use date format)
+  expect(fromNow(new Date("2022-01-15T12:00:00.000Z"))).toMatch(/Jan 15, 2022/);
+
+  // Restore real timers
+  import.meta.vitest?.vi.useRealTimers();
+});
+
+export function fromNowDetailed(date: Date): {
+  result: string,
+  /**
+   * May be Infinity if the result will never change.
+   */
+  secondsUntilChange: number,
+} {
+  if (!(date instanceof Date)) {
+    throw new Error(`fromNow only accepts Date objects (received: ${date})`);
+  }
+
+  const now = new Date();
+  const elapsed = now.getTime() - date.getTime();
+
+  let remainingInUnit = Math.abs(elapsed) / 1000;
+  if (remainingInUnit < 15) {
+    return {
+      result: 'just now',
+      secondsUntilChange: 15 - remainingInUnit,
+    };
+  }
+  let unitInSeconds = 1;
+  for (const [nextUnitSize, unitName] of agoUnits) {
+    const rounded = Math.round(remainingInUnit);
+    if (rounded < nextUnitSize) {
+      if (elapsed < 0) {
+        return {
+          result: `in ${rounded} ${unitName}${rounded === 1 ? '' : 's'}`,
+          secondsUntilChange: remainder((remainingInUnit - rounded + 0.5) * unitInSeconds, unitInSeconds),
+        };
+      } else {
+        return {
+          result: `${rounded} ${unitName}${rounded === 1 ? '' : 's'} ago`,
+          secondsUntilChange: remainder((rounded - remainingInUnit - 0.5) * unitInSeconds, unitInSeconds),
+        };
+      }
+    }
+    unitInSeconds *= nextUnitSize;
+    remainingInUnit /= nextUnitSize;
+  }
+
+  return {
+    result: date.toLocaleDateString('en-US', { year: 'numeric', month: 'short', day: 'numeric' }),
+    secondsUntilChange: Infinity,
+  };
+}
+
+/**
+ * Returns a string representation of the given date in the format expected by the `datetime-local` input type.
+ */
+export function getInputDatetimeLocalString(date: Date): string {
+  date = new Date(date);
+  date.setMinutes(date.getMinutes() - date.getTimezoneOffset());
+  return date.toISOString().slice(0, 19);
+}
+
+import.meta.vitest?.test("getInputDatetimeLocalString", ({ expect }) => {
+  // Use Vitest's fake timers to ensure consistent timezone behavior
+  import.meta.vitest?.vi.useFakeTimers();
+
+  // Test with a specific date
+  const mockDate = new Date("2023-01-15T12:30:45.000Z");
+  const result = getInputDatetimeLocalString(mockDate);
+
+  // The result should be in the format YYYY-MM-DDTHH:MM:SS
+  expect(result).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/);
+
+  // Test with different dates
+  const dates = [
+    new Date("2023-01-01T00:00:00.000Z"),
+    new Date("2023-06-15T23:59:59.000Z"),
+    new Date("2023-12-31T12:34:56.000Z"),
+  ];
+
+  for (const date of dates) {
+    const result = getInputDatetimeLocalString(date);
+    expect(result).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/);
+  }
+
+  // Restore real timers
+  import.meta.vitest?.vi.useRealTimers();
+});
+
+
+export type Interval = [number, 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year'];
+export type DayInterval = [number, 'day' | 'week' | 'month' | 'year'];
+
+function applyInterval(date: Date, times: number, interval: Interval): Date {
+  if (!intervalSchema.isValidSync(interval)) {
+    throw new HexclaveAssertionError(`Invalid interval`, { interval });
+  }
+  const [amount, unit] = interval;
+  switch (unit) {
+    case 'millisecond': {
+      date.setMilliseconds(date.getMilliseconds() + amount * times);
+      break;
+    }
+    case 'second': {
+      date.setSeconds(date.getSeconds() + amount * times);
+      break;
+    }
+    case 'minute': {
+      date.setMinutes(date.getMinutes() + amount * times);
+      break;
+    }
+    case 'hour': {
+      date.setHours(date.getHours() + amount * times);
+      break;
+    }
+    case 'day': {
+      date.setDate(date.getDate() + amount * times);
+      break;
+    }
+    case 'week': {
+      date.setDate(date.getDate() + amount * times * 7);
+      break;
+    }
+    case 'month': {
+      date.setMonth(date.getMonth() + amount * times);
+      break;
+    }
+    case 'year': {
+      date.setFullYear(date.getFullYear() + amount * times);
+      break;
+    }
+    default: {
+      throw new HexclaveAssertionError(`Invalid interval despite schema validation`, { interval });
+    }
+  }
+  return date;
+}
+
+export function subtractInterval(date: Date, interval: Interval): Date {
+  return applyInterval(date, -1, interval);
+}
+
+export function addInterval(date: Date, interval: Interval): Date {
+  return applyInterval(date, 1, interval);
+}
+
+export const FAR_FUTURE_DATE = new Date(8640000000000000); // 13 Sep 275760 00:00:00 UTC
+
+function getMsPerDayIntervalUnit(unit: 'day' | 'week'): number {
+  if (unit === 'day') {
+    return 24 * 60 * 60 * 1000;
+  }
+  return 7 * 24 * 60 * 60 * 1000;
+}
+
+
+export function getIntervalsElapsed(anchor: Date, to: Date, repeat: DayInterval): number {
+  const [amount, unit] = repeat;
+  if (to <= anchor) return 0;
+  if (unit === 'day' || unit === 'week') {
+    const msPerUnit = getMsPerDayIntervalUnit(unit);
+    const diffMs = to.getTime() - anchor.getTime();
+    return Math.floor(diffMs / (msPerUnit * amount));
+  }
+  if (["month", "year"].includes(unit)) {
+    let count = 0;
+    let current = new Date(anchor);
+    for (; ;) {
+      const next = addInterval(new Date(current), [amount, unit]);
+      if (next > to) break;
+      current = next;
+      count += 1;
+    }
+    return count;
+  }
+  return 0;
+}
+
+import.meta.vitest?.test("getIntervalsElapsed", ({ expect }) => {
+  const anchor = new Date('2025-01-01T00:00:00.000Z');
+  const to = new Date('2025-01-15T00:00:00.000Z');
+  expect(getIntervalsElapsed(anchor, to, [1, 'week'])).toBe(2);
+  expect(getIntervalsElapsed(anchor, to, [3, 'day'])).toBe(4);
+
+  const mAnchor = new Date('2023-01-31T00:00:00.000Z');
+  const mTo = new Date('2023-03-01T00:00:00.000Z');
+  expect(getIntervalsElapsed(mAnchor, mTo, [1, 'month'])).toBe(0);
+
+  const yAnchor = new Date('2020-01-01T00:00:00.000Z');
+  const yTo = new Date('2022-06-01T00:00:00.000Z');
+  expect(getIntervalsElapsed(yAnchor, yTo, [1, 'year'])).toBe(2);
+});

package/src/utils/dev-env-state-path.ts

@@ -0,0 +1,14 @@
+import { homedir } from "os";
+import { join } from "path";
+
+export function defaultHexclaveDevEnvStatePath(): string {
+  if (process.platform === "win32") {
+    const localAppData = process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local");
+    return join(localAppData, "Hexclave", "dev-envs.json");
+  }
+  return join(homedir(), ".stack", "dev-envs.json");
+}
+
+export function hexclaveDevEnvStatePath(): string {
+  return process.env.STACK_DEV_ENVS_PATH ?? defaultHexclaveDevEnvStatePath();
+}

package/src/utils/dom.tsx

@@ -0,0 +1,7 @@
+export function hasClickableParent(element: HTMLElement): boolean {
+  const parent = element.parentElement;
+  if (!parent) return false;
+  if (parent.dataset.n2Clickable) return true;
+
+  return hasClickableParent(element.parentElement);
+}

package/src/utils/env.tsx

@@ -0,0 +1,117 @@
+import { HexclaveAssertionError, throwErr } from "./errors";
+import { deindent } from "./strings";
+
+export function isBrowserLike() {
+  return typeof window !== "undefined" && typeof document !== "undefined" && typeof document.createElement !== "undefined";
+}
+
+// newName: oldName
+const ENV_VAR_RENAME: Record<string, string[]> = {
+  NEXT_PUBLIC_STACK_API_URL: ['STACK_BASE_URL', 'NEXT_PUBLIC_STACK_URL'],
+};
+
+/**
+ * Hexclave rebrand: compute the `HEXCLAVE_*`-prefixed equivalent of a `STACK_*`
+ * env var name by replacing the first `STACK_` occurrence with `HEXCLAVE_`.
+ * Covers `STACK_FOO`, `NEXT_PUBLIC_STACK_FOO`, `NEXT_PUBLIC_BROWSER_STACK_FOO`,
+ * `NEXT_PUBLIC_SERVER_STACK_FOO`, `VITE_STACK_FOO`. Returns `undefined` when the
+ * name has no `STACK_` segment (caller should behave exactly as before).
+ */
+function getHexclaveEnvVarName(name: string): string | undefined {
+  if (!name.includes("STACK_")) {
+    return undefined;
+  }
+  return name.replace("STACK_", "HEXCLAVE_");
+}
+
+/**
+ * Returns the environment variable with the given name, returning the default (if given) or throwing an error (otherwise) if it's undefined or the empty string.
+ */
+export function getEnvVariable(name: string, defaultValue?: string | undefined): string {
+  if (isBrowserLike()) {
+    throw new Error(deindent`
+      Can't use getEnvVariable on the client because Next.js transpiles expressions of the kind process.env.XYZ at build-time on the client.
+    
+      Use process.env.XYZ directly instead.
+    `);
+  }
+  if (name === "NEXT_RUNTIME") {
+    throw new Error(deindent`
+      Can't use getEnvVariable to access the NEXT_RUNTIME environment variable because it's compiled into the client bundle.
+    
+      Use getNextRuntime() instead.
+    `);
+  }
+
+  // throw error if the old name is used as the retrieve key
+  for (const [newName, oldNames] of Object.entries(ENV_VAR_RENAME)) {
+    if (oldNames.includes(name)) {
+      throwErr(`Environment variable ${name} has been renamed to ${newName}. Please update your configuration to use the new name.`);
+    }
+  }
+
+  // Hexclave rebrand: prefer the HEXCLAVE_*-prefixed equivalent, fall back to the STACK_* name.
+  const hexclaveName = getHexclaveEnvVarName(name);
+  let value = (hexclaveName ? process.env[hexclaveName] : undefined) ?? process.env[name];
+
+  // check the key under the old name if the new name is not found
+  if (!value && ENV_VAR_RENAME[name] as any) {
+    for (const oldName of ENV_VAR_RENAME[name]) {
+      // Hexclave rebrand: also accept the HEXCLAVE_*-prefixed equivalent of each old alias.
+      const hexclaveOldName = getHexclaveEnvVarName(oldName);
+      value = (hexclaveOldName ? process.env[hexclaveOldName] : undefined) ?? process.env[oldName];
+      if (value) break;
+    }
+  }
+
+  if (!value) {
+    if (defaultValue !== undefined) {
+      value = defaultValue;
+    } else {
+      throwErr(`Missing environment variable: ${name}`);
+    }
+  }
+
+  return value;
+}
+
+export function getEnvBoolean(name: string): boolean {
+  const value = getEnvVariable(name, "false");
+  if (value === "true") {
+    return true;
+  } else if (value === "false") {
+    return false;
+  } else {
+    throw new HexclaveAssertionError(`Environment variable ${name} must be either "true" or "false": found ${JSON.stringify(value)}`);
+  }
+}
+
+export function getNextRuntime() {
+  // This variable is compiled into the client bundle, so we can't use getEnvVariable here.
+  return process.env.NEXT_RUNTIME || throwErr("Missing environment variable: NEXT_RUNTIME");
+}
+
+export function getNodeEnvironment() {
+  return getEnvVariable("NODE_ENV", "");
+}
+
+/**
+ * Browser-safe access to `process.env` for server-only or genuinely dynamic
+ * env-var lookups. Returns `undefined` when `process` is not defined (e.g. in
+ * a Vite browser bundle without a `process` shim).
+ *
+ * Note: uses `process.env[name]` (bracket form), which is NOT recognized by
+ * Next.js / webpack DefinePlugin for compile-time inlining. If you need
+ * build-time inlining for a `NEXT_PUBLIC_*` var, use the literal dot-form at
+ * the call site, guarded with `typeof process`:
+ *
+ *   const value = (typeof process !== "undefined" ? process.env.NEXT_PUBLIC_FOO : undefined);
+ */
+export function getProcessEnv(name: string): string | undefined {
+  if (typeof process === "undefined" || typeof process.env === "undefined") {
+    return undefined;
+  }
+  // Hexclave rebrand: prefer the HEXCLAVE_*-prefixed equivalent, fall back to the STACK_* name.
+  const hexclaveName = getHexclaveEnvVarName(name);
+  return (hexclaveName ? process.env[hexclaveName] : undefined) ?? process.env[name];
+}

package/src/utils/errors.tsx

@@ -0,0 +1,284 @@
+import { globalVar } from "./globals";
+import { Json } from "./json";
+import { pick } from "./objects";
+import { nicify } from "./strings";
+
+
+export function throwErr(errorMessage: string, extraData?: any): never;
+export function throwErr(error: Error): never;
+export function throwErr(...args: StatusErrorConstructorParameters): never;
+export function throwErr(...args: any[]): never {
+  if (typeof args[0] === "string") {
+    throw new HexclaveAssertionError(args[0], args[1]);
+  } else if (args[0] instanceof Error) {
+    throw args[0];
+  } else {
+    // @ts-expect-error
+    throw new StatusError(...args);
+  }
+}
+
+function removeStacktraceNameLine(stack: string): string {
+  // some browsers (eg. Chrome) prepend the stack with an extra line with the error name
+  const addsNameLine = new Error().stack?.startsWith("Error\n");
+  return stack.split("\n").slice(addsNameLine ? 1 : 0).join("\n");
+}
+
+
+/**
+ * Concatenates the (original) stacktraces of the given errors onto the first.
+ *
+ * Note: Very often, the concatStacktracesIfRejected function in promises.tsx is an easier way to use this function.
+ *
+ * Useful when you invoke an async function to receive a promise without awaiting it immediately. Browsers are smart
+ * enough to keep track of the call stack in async function calls when you invoke `.then` within the same async tick,
+ * but if you don't, the stacktrace will be lost.
+ *
+ * Here's an example of the unwanted behavior:
+ *
+ * ```tsx
+ * async function log() {
+ *   await wait(0);  // put the task on the event loop
+ *   console.log(new Error().stack);
+ * }
+ *
+ * async function main() {
+ *   await log();  // good; prints both "log" and "main" on the stacktrace
+ *   log();  // bad; prints only "log" on the stacktrace
+ * }
+ * ```
+ */
+export function concatStacktraces(first: Error, ...errors: Error[]): void {
+  // some browsers (eg. Firefox) add an extra empty line at the end
+  const addsEmptyLineAtEnd = first.stack?.endsWith("\n");
+
+
+  // Add a reference to this function itself so that we know that stacktraces were concatenated
+  // If you are coming here from a stacktrace, please know that the two parts before and after this line are different
+  // stacktraces that were concatenated with concatStacktraces
+  const separator = removeStacktraceNameLine(new Error().stack ?? "").split("\n")[0];
+
+
+  for (const error of errors) {
+    const toAppend = removeStacktraceNameLine(error.stack ?? "");
+    first.stack += (addsEmptyLineAtEnd ? "" : "\n") + separator + "\n" + toAppend;
+  }
+}
+
+
+export class HexclaveAssertionError extends Error {
+  constructor(message: string, public readonly extraData?: Record<string, any> & ErrorOptions) {
+    const disclaimer = `\n\nThis is likely an error in Hexclave. Please make sure you are running the newest version and report it.`;
+    super(`${message}${message.endsWith(disclaimer) ? "" : disclaimer}`, pick(extraData ?? {}, ["cause"]));
+
+    Object.defineProperty(this, "customCaptureExtraArgs", {
+      get() {
+        return [this.extraData];
+      },
+      enumerable: false,
+    });
+
+    // Use literal dot-form (guarded with `typeof process`) so Next.js / webpack
+    // DefinePlugin can inline the value at build time. See getProcessEnv in ./env.
+    if ((typeof process !== "undefined" ? process.env.NEXT_PUBLIC_STACK_DEBUGGER_ON_ASSERTION_ERROR : undefined) === "true") {
+      debugger;
+    }
+  }
+}
+HexclaveAssertionError.prototype.name = "HexclaveAssertionError";
+
+
+export function errorToNiceString(error: unknown): string {
+  if (!(error instanceof Error)) return `${typeof error}<${nicify(error)}>`;
+  return nicify(error, { maxDepth: 8 });
+}
+
+
+export type CaptureLevel = "error" | "warning";
+
+type ErrorSink = (location: string, error: unknown, level: CaptureLevel, ...extraArgs: unknown[]) => void;
+
+const errorSinks = new Set<ErrorSink>();
+export function registerErrorSink(sink: ErrorSink): void {
+  if (errorSinks.has(sink)) {
+    return;
+  }
+  errorSinks.add(sink);
+}
+registerErrorSink((location, error, level, ...extraArgs) => {
+  const logger = level === "warning" ? console.warn : console.error;
+  const colorCode = level === "warning" ? "\x1b[43m" : "\x1b[41m";
+  const label = level === "warning" ? "warning" : "error";
+  logger(
+    `${colorCode}Captured ${label} in ${location}:`,
+    // HACK: Log a nicified version of the error to get around buggy Next.js pretty-printing
+    // https://www.reddit.com/r/nextjs/comments/1gkxdqe/comment/m19kxgn/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button
+    errorToNiceString(error),
+    ...extraArgs,
+    "\x1b[0m",
+  );
+});
+registerErrorSink((location, error, level, ...extraArgs) => {
+  globalVar.hexclaveCapturedErrors = globalVar.hexclaveCapturedErrors ?? [];
+  globalVar.hexclaveCapturedErrors.push({ location, error, level, extraArgs });
+});
+
+function dispatchToSinks(location: string, error: unknown, level: CaptureLevel): void {
+  for (const sink of errorSinks) {
+    sink(
+      location,
+      error,
+      level,
+      ...error && (typeof error === 'object' || typeof error === 'function') && "customCaptureExtraArgs" in error && Array.isArray(error.customCaptureExtraArgs) ? (error.customCaptureExtraArgs as any[]) : [],
+    );
+  }
+}
+
+/**
+ * Captures an error and sends it to the error sinks (most notably, Sentry). Errors caught with captureError are
+ * supposed to be seen by an engineer, so they should be actionable and important.
+ *
+ * The location string is a machine-readable ID, and should hence not contain spaces or anything like that. Good
+ * examples are: "api-route-handler", "renderPart()", etc.
+ *
+ * Errors that bubble up to the top of runAsynchronously or a route handler are already captured with captureError.
+ */
+export function captureError(location: string, error: unknown): void {
+  dispatchToSinks(location, error, "error");
+}
+
+/**
+ * Like captureError, but logs at warning level. Use for issues that an engineer should know about but that aren't
+ * severe enough to be treated as an error (e.g. recoverable failures in background tasks).
+ */
+export function captureWarning(location: string, error: unknown): void {
+  dispatchToSinks(location, error, "warning");
+}
+
+
+type Status = {
+  statusCode: number,
+  message: string,
+};
+
+type StatusErrorConstructorParameters =
+| [
+  status: Status,
+  message?: string
+]
+| [
+  statusCode: number | Status,
+  message: string,
+];
+
+export class StatusError extends Error {
+  private readonly __stackStatusErrorBrand = "stack-status-error-brand-sentinel" as const;
+  public name = "StatusError";
+  public readonly statusCode: number;
+
+  public static BadRequest = { statusCode: 400, message: "Bad Request" };
+  public static Unauthorized = { statusCode: 401, message: "Unauthorized" };
+  public static PaymentRequired = { statusCode: 402, message: "Payment Required" };
+  public static Forbidden = { statusCode: 403, message: "Forbidden" };
+  public static NotFound = { statusCode: 404, message: "Not Found" };
+  public static MethodNotAllowed = { statusCode: 405, message: "Method Not Allowed" };
+  public static NotAcceptable = { statusCode: 406, message: "Not Acceptable" };
+  public static ProxyAuthenticationRequired = { statusCode: 407, message: "Proxy Authentication Required" };
+  public static RequestTimeout = { statusCode: 408, message: "Request Timeout" };
+  public static Conflict = { statusCode: 409, message: "Conflict" };
+  public static Gone = { statusCode: 410, message: "Gone" };
+  public static LengthRequired = { statusCode: 411, message: "Length Required" };
+  public static PreconditionFailed = { statusCode: 412, message: "Precondition Failed" };
+  public static PayloadTooLarge = { statusCode: 413, message: "Payload Too Large" };
+  public static URITooLong = { statusCode: 414, message: "URI Too Long" };
+  public static UnsupportedMediaType = { statusCode: 415, message: "Unsupported Media Type" };
+  public static RangeNotSatisfiable = { statusCode: 416, message: "Range Not Satisfiable" };
+  public static ExpectationFailed = { statusCode: 417, message: "Expectation Failed" };
+  public static ImATeapot = { statusCode: 418, message: "I'm a teapot" };
+  public static MisdirectedRequest = { statusCode: 421, message: "Misdirected Request" };
+  public static UnprocessableEntity = { statusCode: 422, message: "Unprocessable Entity" };
+  public static Locked = { statusCode: 423, message: "Locked" };
+  public static FailedDependency = { statusCode: 424, message: "Failed Dependency" };
+  public static TooEarly = { statusCode: 425, message: "Too Early" };
+  public static UpgradeRequired = { statusCode: 426, message: "Upgrade Required" };
+  public static PreconditionRequired = { statusCode: 428, message: "Precondition Required" };
+  public static TooManyRequests = { statusCode: 429, message: "Too Many Requests" };
+  public static RequestHeaderFieldsTooLarge = { statusCode: 431, message: "Request Header Fields Too Large" };
+  public static UnavailableForLegalReasons = { statusCode: 451, message: "Unavailable For Legal Reasons" };
+
+  public static InternalServerError = { statusCode: 500, message: "Internal Server Error" };
+  public static NotImplemented = { statusCode: 501, message: "Not Implemented" };
+  public static BadGateway = { statusCode: 502, message: "Bad Gateway" };
+  public static ServiceUnavailable = { statusCode: 503, message: "Service Unavailable" };
+  public static GatewayTimeout = { statusCode: 504, message: "Gateway Timeout" };
+  public static HTTPVersionNotSupported = { statusCode: 505, message: "HTTP Version Not Supported" };
+  public static VariantAlsoNegotiates = { statusCode: 506, message: "Variant Also Negotiates" };
+  public static InsufficientStorage = { statusCode: 507, message: "Insufficient Storage" };
+  public static LoopDetected = { statusCode: 508, message: "Loop Detected" };
+  public static NotExtended = { statusCode: 510, message: "Not Extended" };
+  public static NetworkAuthenticationRequired = { statusCode: 511, message: "Network Authentication Required" };
+
+
+  constructor(...args: StatusErrorConstructorParameters);
+  constructor(
+    status: number | Status,
+    message?: string,
+  ) {
+    if (typeof status === "object") {
+      message ??= status.message;
+      status = status.statusCode;
+    }
+    super(message);
+    this.statusCode = status;
+    if (!message) {
+      throw new HexclaveAssertionError("StatusError always requires a message unless a Status object is passed", { cause: this });
+    }
+  }
+
+  public static isStatusError(error: unknown): error is StatusError {
+    // like instanceof, but also works for errors thrown in other realms or by different versions of the same package
+    return typeof error === "object" && error !== null && "__stackStatusErrorBrand" in error && error.__stackStatusErrorBrand === "stack-status-error-brand-sentinel";
+  }
+
+  public isClientError() {
+    return this.statusCode >= 400 && this.statusCode < 500;
+  }
+
+  public isServerError() {
+    return !this.isClientError();
+  }
+
+  public getStatusCode(): number {
+    return this.statusCode;
+  }
+
+  public getBody(): Uint8Array {
+    return new TextEncoder().encode(this.message);
+  }
+
+  public getHeaders(): Record<string, string[]> {
+    return {
+      "Content-Type": ["text/plain; charset=utf-8"],
+    };
+  }
+
+  public toDescriptiveJson(): Json {
+    return {
+      status_code: this.getStatusCode(),
+      message: this.message,
+      headers: this.getHeaders(),
+    };
+  }
+
+  /**
+   * @deprecated this is not a good way to make status errors human-readable, use toDescriptiveJson instead
+   */
+  public toHttpJson(): Json {
+    return {
+      status_code: this.statusCode,
+      body: this.message,
+      headers: this.getHeaders(),
+    };
+  }
+}
+StatusError.prototype.name = "StatusError";