feat(ses): add support for "code" prop in SES-managed Errors

[boneskull]

• Adds a new string option to AssertMakeErrorOptions, code
• If a string, will be an non-enumerable property of the Error instance returned by makeError.
• To avoid mutating global types, a new type SesError is introduced which is simply Error & {code?: string}.

Note that code is expected to be a string here, but only by convention; the language will not enforce this (as per the below proposal).

Ref: https://github.com/tc39-transfer/proposal-error-code-property

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1ec13b7

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[boneskull]

What I'd really like to see here is a makeError which is generic on the error constructor type (so that it would return a value of that type), but the signature is such that it is not possible--the default parameter of globalThis.Error creates a type error when it's generic, and removing the default value is invalid syntax (since the previous message/details parameter also has a default value).

endo/packages/ses/src/error/assert.js

Lines 341 to 352 in e6d46c7

	const makeError = (
	optDetails = redactedDetails`Assert failed`,
	errConstructor = globalThis.Error,
	{
	errorName = undefined,
	cause = undefined,
	errors = undefined,
	sanitize = true,
	code = undefined,
	} = {},
	) => {
	// Promote string-valued `optDetails` into a minimal DetailsParts

The workaround is to just wrap makeError in another function.

[boneskull]

Open to naming suggestions

[boneskull]

(We could have used module augmentation to extend the global Error interface with a code?: string prop, but that would affect all downstream consumers of ses, which would be inconsiderate)

[erights]

Under any name, I don't like introducing a new type for this purpose if possible.

What about cause and errors? Do they have this problem too? If not, can we treat code the same way? Once we support SuppressedError (hopefully soon) we will also need to support the further instance properties error and suppressed.

[boneskull]

They don't have the same problem, because Error.cause and AggregateError.errors are in the TS lib.

Our options are:

1. Create a new type (as this PR does)
2. Augment the global Error type with a code prop
   This is hazardous because it will affect downstream consumers; anyone pulling in ses will have a global Error with a code prop on it. If we do not publish the augmentation, types will work in a development environment, but will be broken downstream.
3. Fudge it with // @ts-expect-error everywhere code is referenced (gross)

I'm not sure what TS' policy is on adopting proposals (if they have one), but I think it's probably too early to ask.

---

That being said, code will/should/might end up in the TS lib eventually, at which point we can refactor away the custom type and/or alias it to Error.

[kriskowal]

Needs changeset and consensus on names.

[erights]

Under any name, I don't like introducing a new type for this purpose if possible.

What about cause and errors? Do they have this problem too? If not, can we treat code the same way? Once we support SuppressedError (hopefully soon) we will also need to support the further instance properties error and suppressed.

[erights]

See also DRAFT PRs #2223 and #2429 . Like them, we need to coordinate this change with @endo/pass-style and @endo/marshal so that .code is actually passed. Doesn't need to happen in this PR, but that is my preference since it should be a coordinated change. Please borrow as much as you like from those other draft PRs.

[boneskull]

See also DRAFT PRs #2223 and #2429 . Like them, we need to coordinate this change with @endo/pass-style and @endo/marshal so that .code is actually passed. Doesn't need to happen in this PR, but that is my preference since it should be a coordinated change. Please borrow as much as you like from those other draft PRs.

@erights What should I be looking at there? I'm unfamiliar with both of those packages and any discussions around either PR.

I'm operating under the assumption that this PR only satisfies the (fairly minimal) requirements of @endo/compartment-mapper so that it can be consumed sooner rather than later.

I'd expect we'd extend the implementation and/or adopt in other packages when ready. Are you concerned about shipping this in ses as-is? If so, would you be amenable to moving the implementation into @endo/compartment-mapper temporarily so it can be trialed in that context, and then re-integrating with ses in the future?

[mhofman]

FYI, I found myself in need of creating errors with a .code, so I overrode and created extra helpers around @endo/errors

In particular I'm adding an XError helper to create Error using template literals like Fail does but without throwing (a wrapper around makeError but without the constructor and details cruft), and make both this XError and Fail chainable to define the options that makeError accepts (credit to @gibson042 for the idea).

errors.ts:

import { makeError as originalMakeError, X } from "@endo/errors";

export * from "@endo/errors";

type Details = NonNullable<Parameters<typeof originalMakeError>[0]>;
type GenericErrorConstructor = NonNullable<
  Parameters<typeof originalMakeError>[1]
>;
type AssertMakeErrorOptions = NonNullable<
  Parameters<typeof originalMakeError>[2]
> & {
  code?: string;
};

type ChainedErrorMaker<T> = ((
  template: TemplateStringsArray | string[],
  ...args: any[]
) => T) & {
  code(code: string): ChainedErrorMaker<T>;
  instance(ctor: GenericErrorConstructor): ChainedErrorMaker<T>;
  options(options: AssertMakeErrorOptions): ChainedErrorMaker<T>;
};

const assertFailedDetails = X`Check failed`;

export const makeError = (
  details: Details = assertFailedDetails,
  errConstructor: GenericErrorConstructor | undefined = undefined,
  options: AssertMakeErrorOptions | undefined = undefined,
): Error => {
  const { code, sanitize = false, ...makeErrorOptions } = options ?? {};
  const hasCode = code !== undefined;
  const error = originalMakeError(details, errConstructor, {
    ...makeErrorOptions,
    // `code` and `sanitize` are mutually exclusive options, ignore sanitize
    sanitize: !hasCode && sanitize,
  });
  if (code !== undefined) {
    Object.defineProperty(error, "code", {
      value: code,
      enumerable: false,
      configurable: true,
      writable: true,
    });
  }
  return error;
};

export const fail = (
  /** The details of what was asserted */
  details: Details = assertFailedDetails,
  /** An optional alternate error constructor to use */
  errConstructor: GenericErrorConstructor | undefined = undefined,
  options: AssertMakeErrorOptions | undefined = undefined,
): never => {
  throw makeError(details, errConstructor, options);
};

const makeChainedHelper = <T>(
  fn: (...args: Parameters<typeof makeError>) => T,
) => {
  const name = fn.name && fn.name.charAt(0).toUpperCase() + fn.name.slice(1);
  const maker = (
    options: AssertMakeErrorOptions = {},
    constructor?: GenericErrorConstructor | undefined,
  ): ChainedErrorMaker<T> => {
    // XXX: Consider defaulting to carrying over the code of any error passed in values
    // with the caveat that such value may be classified (quoted or bare)
    const Fail: ChainedErrorMaker<T> = (template, ...values) =>
      fn(X(template, ...values), constructor, options);
    Fail.code = (code: string) => maker({ ...options, code }, constructor);
    Fail.instance = (ctor: GenericErrorConstructor) => maker(options, ctor);
    Fail.options = (opts: AssertMakeErrorOptions) =>
      maker({ ...options, ...opts }, constructor);
    Object.defineProperty(Fail, "name", { value: name });
    return Fail;
  };
  return maker();
};

export const Fail = makeChainedHelper(fail);

export const XError = makeChainedHelper(makeError);

[boneskull]

FYI, I found myself in need of creating errors with a .code, so I overrode and created extra helpers around @endo/errors

In particular I'm adding an XError helper to create Error using template literals like Fail does but without throwing (a wrapper around makeError but without the constructor and details cruft), and make both this XError and Fail chainable to define the options that makeError accepts (credit to @gibson042 for the idea).

errors.ts:

@mhofman Wait does this mean I can rewrite @endo/compartment-mapper in TS?? 😄

[mhofman]

@mhofman Wait does this mean I can rewrite @endo/compartment-mapper in TS?? 😄

When #3137 lands, yes

[boneskull]

📚 Pull Request Stack

• branch: master
  • feat(ses): add support for "code" prop in SES-managed Errors #3130 - branch: boneskull/error-code (this PR)

---

Managed by gh-stack