123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577
// Copyright 2022 Connor Logan. All rights reserved. MIT License.// This module is browser-compatible.
// This module is heavily inspired by https://github.com/blitz-js/superjson
// TODO: Automatically escape strings for XSS, see https://github.com/yahoo/serialize-javascript// TODO: Support for ArrayBuffer/View// TODO: Support for functions?
/** * Initializer arguments for constructing HttpErrors, which can expose arbitrary * data and status codes during de/serialization. */ export interface HttpErrorInit {  /** An HTTP status code describing what kind of error this is. */  status?: number;  /** Optional data exposed to the client when this error is serialized. */  expose?: unknown;  /** Other details about the error. Omitted during serialization. */  detail?: Record<string, unknown>;}
/** An error class for describing exceptions during HTTP processing. */export class HttpError extends Error {  /** An HTTP status code describing what kind of error this is. */  status: number;  /** Optional data exposed to the client when this error is serialized. */  expose?: unknown;  /** Other details about the error. Omitted during serialization. */  detail: Record<string, unknown>;
  constructor(message: string, init?: HttpErrorInit) {    super(message);    this.status = init?.status || 500;    this.expose = init?.expose;    this.detail = init?.detail || {};  }}
/** * A group of functions used to recognize (check), serialize, and deserialize * objects and special values that are not strings, basic numbers, booleans, or * nulls into objects that are JSON compatible. */export interface Serializer<I = unknown, O = unknown> {  /**   * Function for checking if the serializer applies to a given value. JSON   * primitives like basic numbers, strings, booleans, and nulls skip all   * serializers and are returned as-is. For example, `check: (v) => typeof v   * === "string"` always returns false.   */  check(value: unknown): boolean;  /**   * Transforms the value into its output on the resulting json-compatible   * object. The value returned by this function will be reserialized; the   * output does not need to be JSON-compatible.    */  serialize(value: I): O;  /**   * Transforms serialized values into their original shape and structure.   * Initially, the value is only constructed from the raw serialized JSON.   * Values that are more complex and need things like referential equality or   * non-POJO/Array objects will need to use the `whenDone` registration   * function to access the equivalent of the value returned from `serialize()`   * when the value was serialized. (See the docs for the WhenDone type for more   * details.)   */  deserialize(raw: unknown, whenDone: WhenDone<O>): I;}
/** * A Serializer's `deserialize()` function receives the raw serialized JSON * value as its first argument and this registration function as the second. * Functions registered with whenDone will be run last-in-first-out (stack * order) when the raw JSON has been processed into the final object instance. * WhenDone functions are needed whenever the serialized data is more complex * than simple JSON values, for example when referential equality needs to be * maintained or when the serialize function returns anything that needs to be * re-serialized by some other serializer. Referenced objects may not be fully * initialized when the registered function is called, but its instance will be * instantiated so that references can be fixed. * * Credit goes to [json-dry](https://github.com/11ways/json-dry) for the * whenDone concept. */export type WhenDone<O> = (fn: (serialized: O) => void) => void;
/** * Constructs a Serializer. This simply returns the first argument, it's only * used for type annotations. */export function serializer<I = unknown, O = unknown>(  init: Serializer<I, O>,): Serializer<I, O> {  return init;}
/** * Type alias representing a Serializer with any input or output type. Useful * for type constraints. */// deno-lint-ignore no-explicit-anyexport type AnySerializer = Serializer<any, any>;
/** * A group of named Serializer objects. Serializer keys are used to tag * serialized values on the output JSON, which is required in order to correctly * deserialize the value on the other side. */export type Serializers = Record<string, AnySerializer | null>;
function serializerMap(serializers?: Serializers): Map<string, AnySerializer> {  const defaults = new Map<string, AnySerializer>(Object.entries({    httpError: serializer({      check: (v) => v instanceof HttpError,      serialize: (v: HttpError) => ({        status: v.status,        message: v.message,        expose: v.expose,      }),      deserialize: (raw, whenDone) => {        const u = (raw as { status: number; message: string });        const err = new HttpError(u.message, { status: u.status });        whenDone((parsed) => {          err.expose = parsed.expose;        });        return err;      },    }),    error: serializer({      check: (v) => v instanceof Error,      serialize: (v: Error) => v.message,      deserialize: (raw) => new Error(raw as string),    }),    date: serializer({      check: (v) => v instanceof Date,      serialize: (v: Date) => v.toJSON(),      deserialize: (raw) => new Date(raw as string),    }),    undefined: serializer({      check: (v) => typeof v === "undefined",      serialize: () => null,      deserialize: () => undefined,    }),    symbol: serializer({      check: (v) => typeof v === "symbol",      serialize: (v: symbol) => v.description,      deserialize: (raw) => Symbol(raw as string),    }),    map: serializer({      check: (v) => v instanceof Map,      serialize: (v: Map<unknown, unknown>) => Array.from(v.entries()),      deserialize: (_, whenDone) => {        const map = new Map();        whenDone(entries => {          entries.forEach(v => map.set(v[0], v[1]));        });        return map;      },    }),    set: serializer({      check: (val) => val instanceof Set,      serialize: (v: Set<unknown>) => Array.from(v.values()),      deserialize: (_, whenDone) => {        const set = new Set();        whenDone(values => {          values.forEach(v => set.add(v));        });        return set;      },    }),    bigint: serializer({      check: (v) => typeof v === "bigint",      serialize: (v: bigint) => v.toString(),      deserialize: (raw) => BigInt(raw as string),    }),    regexp: serializer({      check: (v) => v instanceof RegExp,      serialize: (v: RegExp) => v.toString(),      deserialize: (raw) => {        const r = (raw as string).slice(1).split("/");        return new RegExp(r[0], r[1]);      },    }),    number: serializer({      check: (v) => typeof v === "number" && (        isNaN(v) ||        v === Number.POSITIVE_INFINITY ||        v === Number.NEGATIVE_INFINITY ||        Object.is(v, -0)      ),      serialize: (v: number) => (        isNaN(v) ? "nan"        : v === Number.POSITIVE_INFINITY ? "+infinity"        : v === Number.NEGATIVE_INFINITY ? "-infinity"        : Object.is(v, -0) ? "-0"        : 0 // Should never happen      ),      deserialize: (raw: string) => (        raw === "nan" ? NaN        : raw === "+infinity" ? Number.POSITIVE_INFINITY        : raw === "-infinity" ? Number.NEGATIVE_INFINITY        : raw === "-zero" ? -0        : 0      ),    }),    conflict: serializer({      check: (v) => {        if (!isPojo(v)) {          return false;        }        const keys = Object.keys(v);        return keys.length === 1 && keys[0].startsWith("$");      },      serialize: Object.entries,      deserialize: (_, whenDone) => {        const result: Record<string, unknown> = {};        whenDone(entry => {          result[entry[0][0]] = entry[0][1];        });        return result;      },    }),  }));
  if (!serializers) {    return defaults;  }
  const smap = new Map<string, AnySerializer>();  for (const [k, v] of Object.entries(serializers)) {    if (v === null) {      continue;    }    if (k === "ref" || defaults.has(k)) {      throw new Error(        `Conflict: The serializer key "${k}" is reserved`,      );    }    smap.set(k, v);  }  if (!smap.size) {    return defaults;  }  for (const [k, v] of defaults.entries()) {    smap.set(k, v);  }  return smap;}
/** * Serializes a value recursively until it's JSON-compatible. Serializers can be * plugged in to extend the accepted types beyond what Cav supports by default. * Referential equality will be preserved whenever the same object or symbol * value is encountered more than once. If a value isn't recognized by any of * the provided serializers or the default serializers, an error is thrown. */export function serialize(  value: unknown,  serializers?: Serializers | null,): unknown {  const smap = serializerMap(serializers || {});  const paths = new Map<unknown, string[]>();
  const pathString = (p: string[]) => (    p.map(v => v.replace(/\./g, "\\.")).join(".")  );    const recur = (    val: unknown,    path: string[],  ): unknown => {    if (val && (typeof val === "object" || typeof val === "symbol")) {      if (paths.has(val)) {        return { $ref: pathString(paths.get(val)!) };      }      paths.set(val, path);    }
    if (      val === null ||      typeof val === "string" ||      typeof val === "boolean" ||      (typeof val === "number" && !Object.is(val, -0) && Number.isFinite(val))    ) {      return val;    }
    for (const [name, serializer] of smap.entries()) {      if (serializer.check(val)) {        const key = `$${name}`;        return { [key]: recur(serializer.serialize(val), [...path, key]) };      }    }
    if (isPojo(val)) {      const copy: Record<string, unknown> = {};      for (const [k, v] of Object.entries(val)) {        copy[k] = recur(v, [...path, k]);      }      return copy;    }
    if (Array.isArray(val)) {      const copy: unknown[] = [];      for (let k = 0; k < val.length; k++) {        copy[k] = recur(val[k], [...path, k.toString()]);      }      return copy;    }
    if (      typeof val === "object" &&      "toJSON" in val &&      typeof (val as { toJSON: unknown })["toJSON"] === "function"    ) {      return (val as { toJSON: (key: string) => unknown }).toJSON(        path[path.length - 1],      );    }
    throw new TypeError(      `No matching serializers for ${val}`,    );  };
  return recur(value, [""]);}
/** * Deserializes a value returned by `serialize()` into the original input value. * Referential equality will be restored on the output object. An error will be * thrown if a value was serialized with an unknown/unused serializer. */export function deserialize<T = unknown>(  value: unknown,  serializers?: Serializers | null,): T {  const smap = serializerMap(serializers || {});  const objects = new Map<string, unknown>();  const whenDones: (() => void)[] = [];
  const recur = (val: unknown, path: string) => {    if (!val || typeof val !== "object") {      return val;    }
    if (Array.isArray(val)) {      const copy: unknown[] = [];      objects.set(path, copy);      for (let i = 0; i < val.length; i++) {        copy.push(recur(val[i], path + "." + i.toString()));      }      return copy;    }
    // NOTE: This block should protect against prototype poisoning    if (!isPojo(val)) {      throw new TypeError(        `Non-plain objects can't be deserialized - Path: ${path}`,      );    }
    const keys = Object.keys(val);    if (keys.length === 1 && keys[0] === "$ref") {      const refPath = (val as Record<string, string>).$ref;      const ref = objects.get(refPath);      if (!ref) {        throw new Error(          `Invalid reference "${refPath}" - Path: "${path}"`,        );      }      return ref;    }    if (keys.length === 1 && keys[0].startsWith("$")) {      const tag = keys[0];      const name = keys[0].slice(1);      const serializer = smap.get(name);      if (!serializer) {        throw new Error(          `No matching serializer with name "${name}" - Path: "${path}"`,        );      }
      const raw = val[tag];      let serialized: unknown = undefined;      const result = serializer.deserialize(raw, (fn) => {        whenDones.push(() => fn(serialized));      });      if (result && (        typeof result === "object" ||        typeof result === "symbol"      )) {        objects.set(path, result);      }      serialized = recur(raw, `${path}.${tag}`);      return result;    }
    const copy: Record<string, unknown> = {};    objects.set(path, copy);    for (const [k, v] of Object.entries(val)) {      copy[k] = recur(v, path + "." + k.replace(/\./g, "\\."));    }    return copy;  };    const result = recur(value, "");  let fn = whenDones.pop();  while (fn) {    fn();    fn = whenDones.pop();  }  return result as T;}
/** * Serializes a value into a type that is compatible with a Response BodyInit, * making it easy to serialize values for sending to an external host/client via * HTTP. If a provided value is already compatible with BodyInit, it will be * returned with an appropriate mime type, skipping the serialization process. * During serialization, this function extends the default supported types to * include Blobs and Files. If a Blob is encountered during serialization, the * resulting body will be a multipart FormData that encodes the shape of the * input as well as the blobs that were encountered. Otherwise, a regular JSON * string will be returned. Blobs and Files can be placed anywhere on the input * value, even if they are nested.  */export function serializeBody(value: unknown, serializers?: Serializers): {  body: BodyInit;  mime: string;} {  if (    value instanceof ArrayBuffer ||    value instanceof ReadableStream ||    ArrayBuffer.isView(value)  ) {    return {      body: value,      mime: "application/octet-stream",    };  }  if (typeof value === "string") {    return {      body: value,      mime: "text/plain",    };  }  if (value instanceof URLSearchParams) {    return {      body: value,      mime: "application/x-www-form-urlencoded",    };  }  if (value instanceof Blob) {    return {      body: value,      mime: value.type,    };  }    const form = new FormData();  const fileKeys = new Map<Blob, string>();  const shape = JSON.stringify(serialize(value, {    ...serializers,    __blob: serializer({      check: (v) => v instanceof Blob,      serialize: (v: Blob) => {        let key = fileKeys.get(v);        if (key) {          return key;        }
        key = crypto.randomUUID();        form.set(key, v);        fileKeys.set(v, key);        return key;      },      deserialize: () => null, // Not needed here    }),  }));
  if (!fileKeys.size) {    return {      body: shape,      mime: "application/json",    };  }  form.set("__shape", new Blob([shape], {    type: "application/json",  }));  return {    body: form,    mime: "multipart/form-data",  };}
const mimeStream = /^application\/octet-stream;?/;const mimeString = /^text\/plain;?/;const mimeParams = /^application\/x-www-form-urlencoded;?/;const mimeJson = /^application\/json;?/;const mimeForm = /^multipart\/form-data;?/;
/** * Deserializes a Request or Response object whose body was serialized with * `serializeBody()`. Any Serializers used outside of the library defaults * during serialization need to be provided here as well, or an error may be * thrown. */export async function deserializeBody(  from: Request | Response,  serializers?: Serializers,): Promise<unknown> {  const mime = from.headers.get("content-type");  if (!mime || mime.match(mimeStream)) {    return from.body;  }  if (mime.match(mimeString)) {    return await from.text();  }  if (mime.match(mimeParams)) {    const form = await from.formData();    const params = new URLSearchParams();    for (const [k, v] of form.entries()) {      params.append(k, v as string);    }    return params;  }  if (mime.match(mimeJson)) {    return deserialize(await from.json(), serializers);  }  if (mime.match(mimeForm)) {    const form = await from.formData();    const shape = form.get("__shape");    if (      !shape ||      !(shape instanceof Blob) ||      shape.type !== "application/json"    ) {      return form;    }    return JSON.parse(deserialize(await shape.text(), {      ...serializers,      __blob: serializer({        check: () => false, // Not needed here        serialize: () => false, // Not needed here        deserialize: (raw: string) => {          const blob = form.get(raw);          if (!blob || !(blob instanceof Blob)) {            throw new Error(              `Referenced blob "${raw}" is missing from the form body`,            );          }          return blob;        },      }),    }));  }  return await from.blob();}
/** * Utility function used in the serial functions that determines if an object is * a plain object or not. Because this is such a common operation when checking * and serializing unknown objects, it's being exported as part of the API. */export function isPojo(obj: unknown): obj is Record<string, unknown> {  return (    !!obj &&    typeof obj === "object" &&    (      Object.getPrototypeOf(obj) === Object.prototype ||      Object.getPrototypeOf(obj) === null    )  );}