'assert' package

[turadg]

closes: #1703

Description

A new package to provide the properties of the assert global such that they can be auto-imported in an IDE.

Security Considerations

If this dependency were compromised it could lead a user to thinking they're using the SES's assertions when they're not.

Scaling Considerations

n/a

Documentation Considerations

n/a

Testing Considerations

New tests. Lightly covered yet since the idea is that eventually this package becomes the shim.

Upgrade Considerations

n/a

[kriskowal]

My preference is to export the full name and alias at the import site.

[kriskowal]

My rationale is that abbreviations are for local ergonomics and the exported names need to communicate their purpose. A reviewer unfamiliar with the assert module should be able to infer the meaning from usage and name without leaving the file.

[turadg]

I agree they don't belong in Endo. I'll take them out.

I don't necessarily agree the aliasing should happen at the call site. To make imports easy a repo might have a utils package that re-exports them under abbreviations that are normal in the repo.

[kriskowal]

Thanks. Good enough for this change. We can converge on the broader tension between legibility and ergonomics elsewhere.

[gibson042]

Empty README. 😭

[gibson042]

Why rename the exports?

Suggested change

	// properties with syntax collision
	assertString,
	assertTypeof,
	assertString as string,
	assertTypeof as typeof,

[turadg]

I figured it saves the importer from aliasing them. I'm open to making the change you suggest. I could add a README at that point. Also be my guest if you like to.

[kriskowal]

I do not know how I missed this, and I have no strong feelings one way or the other.

[kriskowal]

Actually, yes, I do feel strongly that all these names should be consistently exported either assertX or x to favor either the import * as assert; assert.x() usage or the import { assert, assertX, assertY } usage.

[kriskowal]

More broadly, these are the design families:

1. import { assert, assertTypeof, assertString, assertEtc } from '@endo/assert';
   assert();
   assertTypeof();
   assertString();

   Express your preference with 🎉

2. import { assert } from '@endo/assert';
   assert();
   assert.typeof();
   assert.string();
   assert.etc();

   Express your preference with ❤️

3. import * as assert from '@endo/assert';
   assert.ok(); // unprecedented
   assert.string();
   assert.typeof();
   assert.etc();

   Express your preference with 🚀

My suspicion is that we disfavor option 3(🚀) collectively. @erights’s position seems consistent with blessing one of these forms and herding usage. @turadg’s motivation for the creation of this package is having an anchor for import inference which is probably satisfied by any of these forms.

I believe that @erights’s position of having a single consistent form actually implies that option 1(🎉) should preclude 2(❤️) by exporting an assert function that unlike globalThis.assert lacks the assert.xyz() properties.

[erights]

Have we resolved that we're doing likewise with
import { quote as q, bare as b, something as X }
with no separate renaming reexport anywhere?

I'm not in love with errorMessage and throwError, though I don't hate them either. But if we're agreed we're pervasively renaming to get to q, b, and X, I have no objection to adding
import { something as Fail }.
If we're all agreed on this much, then lets proceed to bikeshed the two unresolved somethings.

[kriskowal]

My mind appears to be entangled at a quantum level with @michaelfig. I prefer to avoid abbreviation in public API and to scope abbreviations lexically when that improves local legibility. I propose redact for X and throwRedact for Fail.

[erights]

I like redact and throwRedact !!

[Chris-Hibbert]

Not that I like making names longer, but how about throwRedacted?

(and redacted if that seems more consistent to y'all.)

[erights]

After sleeping on it, I do like redacted and throwRedacted better.