refactor!: add retyped-ses package

retyped/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+**/node_modules/

retyped/README.md

@@ -0,0 +1,38 @@
+# Retyped SES
+
+This folder contains retyped versions of some of the SES modules to aid with the discussions in deciding on the best path forward.
+
+This is all still a work in progress just to get some discussions going.
+
+## What to keep in mind…
+
+- **Do not merge**… I butchered your code.
+- JavaScript is the source of truth and `jsconfig.json` ensures this.
+- Type generation is necessary since for consumer-facing types.
+  - TypeScript-based language services are the immediate focus.
+  - JSDoc-based language services are not the immediate focus.
+
+## What to do…
+
+Open `endo/retyped` in a new vscode window and run `yarn`, then manually inspect the files inside the packages and modules subfolders in `endo/retyped/packages/*/test`.
+
+The `build:types` package script must be used to update the `types.d.ts` in the root of each package which can theoretically be run as a `post-install` hook by consumers, but it is not that simple.
+
+## What to look for…
+
+### endo/packages/ses
+
+- endo/packages/ses/package.json
+  - scripts
+    - lint:types
+  - devDependencies
+    - tsd
+    - typescript
+- endo/packages/ses/index.d.ts
+- endo/packages/ses/index-test.d.ts
+
+### endo/retyped/packages/retyped-ses
+
+- endo/retypes/packages/retyped-ses/src/error/internal/*
+- endo/retypes/packages/retyped-ses/test/modules/*
+- endo/retypes/packages/retyped-ses/test/packages/*/*

retyped/package.json

@@ -0,0 +1,9 @@
+{
+  "private": true,
+  "npmClient": "yarn",
+  "workspaces": [
+    "packages/*",
+    "packages/*/test",
+    "packages/*/test/packages/*"
+  ]
+}

retyped/packages/retyped-ses/globals.d.ts

@@ -0,0 +1,3 @@
+declare var assert: typeof globalThis extends { null: any, assert: infer T }
+    ? T
+    : typeof import('src/error/internal/assert').assert;

retyped/packages/retyped-ses/index.d.ts

@@ -0,0 +1,2 @@
+/// <reference path="types.d.ts" />
+/// <reference path="globals.d.ts" />

retyped/packages/retyped-ses/index.js

@@ -0,0 +1,5 @@
+// @ts-check
+import { assert } from './src/error/assert.js';
+
+// @ts-ignore
+globalThis.assert = assert;

retyped/packages/retyped-ses/jsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "./",
+    "downlevelIteration": true,
+    "strictNullChecks": true,
+    "moduleResolution": "node",
+  },
+  "extends": "../../../packages/ses/tsconfig.json",
+  "include": ["index.js", "src/**/*.js"],
+  "exclude": ["./types"]
+}

retyped/packages/retyped-ses/modules.log

@@ -0,0 +1,21 @@
+This file is manually updated with `tsc -p ./tsconfig.json --explainFiles` output.
+
+src/error/internal/details.js
+  Imported via "./details.js" from file 'src/error/internal/assert.js'
+  Imported via "./details.js" from file 'src/error/internal/errors.js'
+  Imported via "./details.js" from file 'src/error/internal/assert.1.js'
+  Matched by include pattern 'src/**/*.js' in 'tsconfig.json'
+src/error/internal/errors.js
+  Imported via "./errors.js" from file 'src/error/internal/assert.js'
+  Imported via "./errors.js" from file 'src/error/internal/assert.1.js'
+  Matched by include pattern 'src/**/*.js' in 'tsconfig.json'
+src/error/internal/assert.js
+  Imported via './internal/assert.js' from file 'src/error/assert.js'
+  Matched by include pattern 'src/**/*.js' in 'tsconfig.json'
+src/error/assert.js
+  Imported via './src/error/assert.js' from file 'index.js'
+  Matched by include pattern 'src/**/*.js' in 'tsconfig.json'
+index.js
+  Matched by include pattern 'index.js' in 'tsconfig.json'
+src/error/internal/assert.1.js
+  Matched by include pattern 'src/**/*.js' in 'tsconfig.json'

retyped/packages/retyped-ses/package.json

@@ -0,0 +1,15 @@
+{
+  "private": true,
+  "name": "retyped-ses",
+  "version": "0.0.1",
+  "type": "module",
+  "devDependencies": {
+    "@types/node": "^18.11.18",
+    "typescript": "^4.9.2"
+  },
+  "npmClient": "yarn",
+  "types": "index.d.ts",
+  "scripts": {
+    "build:types": "tsc -p ./tsconfig.json"
+  }
+}

retyped/packages/retyped-ses/src/error/assert.js

@@ -0,0 +1 @@
+export { assert, makeAssert, fail, error, details } from './internal/assert.js';

retyped/packages/retyped-ses/src/error/internal/assert.1.js

@@ -0,0 +1,87 @@
+// @ts-check
+
+import { makeDetailsToken, DetailsToken } from "./details.js";
+import { makeError } from "./errors.js";
+
+/** @typedef { DetailsToken | { toString(): string } | string } Details */
+
+/**
+ * Asserts that the flag is truthy or throws an error if it is falsy.
+ * 
+ * @param {*} flag Truthy/falsy value
+ * @param {Details} failedDetails The details to throw if flag is falsy
+ * @param {ErrorConstructor} [errorConstructor] The error type to be thrown if flag is falsy
+ */
+function assert(
+    flag,
+    failedDetails = assert.details`Check failed`,
+    errorConstructor = globalThis.Error,
+) {
+    if (!flag) assert.fail(failedDetails, errorConstructor);
+};
+
+/**
+ * Creates a DetailsToken instance.
+ * 
+ * @param {TemplateStringsArray} template 
+ * @param  {...*} args 
+ * @returns {DetailsToken}
+ */
+const details = (template, ...args) => makeDetailsToken(String.raw(template, ...args));
+
+Object.freeze(details);
+assert.details = details;
+export { details };
+
+/** 
+ * Throws an error.
+ * 
+ * @param {Details} failedDetails The details to throw 
+ * @param {ErrorConstructor} errorConstructor The error type to be thrown
+ * @returns {InstanceType<ErrorConstructor>}
+ */
+const fail = (
+    failedDetails = makeDetailsToken(`Check failed`),
+    errorConstructor = globalThis.Error
+) => {
+    throw assert.error(failedDetails, errorConstructor);
+};
+
+Object.freeze(fail);
+assert.fail = fail;
+export { fail };
+
+/**
+ * Creates an error instance.
+ * 
+ * @param {Details} [details] The details of the error
+ * @param {ErrorConstructor} [constructor] The error constructor to use
+ */
+const error = makeError;
+assert.error = error;
+export { error };
+
+/**
+ * Creates an `assert` function that throws an error if the flag is falsy.
+ * 
+ * @param {Function} [raise] 
+ * @returns {typeof assert}
+ */
+const makeAssert = (raise) => Object.freeze(
+    Object.assign(
+        /** @type {typeof assert} */((flag, failedDetails, errorConstructor) => {
+            if (flag) return;
+            const error = assert.error(failedDetails, errorConstructor);
+            if (typeof raise === 'function') raise(error);
+            throw error;
+        }),
+        assert
+    )
+);
+
+Object.freeze(makeAssert);
+assert.makeAssert = makeAssert;
+export { makeAssert };
+
+Object.freeze(assert);
+export { assert };

retyped/packages/retyped-ses/src/error/internal/assert.js

@@ -0,0 +1,88 @@
+// @ts-check
+
+import { makeDetailsToken, DetailsToken } from "./details.js";
+import { makeError } from "./errors.js";
+
+/** @typedef { DetailsToken | { toString(): string } | string } Details */
+
+/**
+ * Asserts that the flag is truthy or throws an error if it is falsy.
+ * 
+ * @param {*} flag Truthy/falsy value
+ * @param {Details} failedDetails The details to throw if flag is falsy
+ * @param {ErrorConstructor} [errorConstructor] The error type to be thrown if flag is falsy
+ */
+function assert(
+    flag,
+    failedDetails = assert.details`Check failed`,
+    errorConstructor = globalThis.Error,
+) {
+    if (!flag) assert.fail(failedDetails, errorConstructor);
+};
+
+/**
+ * Creates a DetailsToken instance.
+ * 
+ * @param {TemplateStringsArray} template 
+ * @param  {...*} args 
+ * @returns {DetailsToken}
+ */
+assert.details = (template, ...args) => makeDetailsToken(String.raw(template, ...args));
+
+Object.freeze(assert.details);
+
+
+/** 
+ * Throws an error.
+ * 
+ * @param {Details} failedDetails The details to throw 
+ * @param {ErrorConstructor} errorConstructor The error type to be thrown
+ * @returns {InstanceType<ErrorConstructor>}
+ */
+assert.fail = (
+    failedDetails = makeDetailsToken(`Check failed`),
+    errorConstructor = globalThis.Error
+) => {
+    throw assert.error(failedDetails, errorConstructor);
+};
+
+Object.freeze(assert.fail);
+
+/**
+ * Creates an error instance.
+ * 
+ * @param {Details} [details] The details of the error
+ * @param {ErrorConstructor} [constructor] The error constructor to use
+ */
+assert.error = makeError;
+
+/**
+ * Creates an `assert` function that throws an error if the flag is falsy.
+ * 
+ * @param {Function} [raise] 
+ * @returns {typeof assert}
+ */
+assert.makeAssert = (raise) => Object.freeze(
+    Object.assign(
+        /** @type {typeof assert} */((flag, failedDetails, errorConstructor) => {
+            if (flag) return;
+            const error = assert.error(failedDetails, errorConstructor);
+            if (typeof raise === 'function') raise(error);
+            throw error;
+        }),
+        assert
+    )
+);
+
+Object.freeze(assert.makeAssert);
+
+Object.freeze(assert);
+
+export const {
+    details,
+    fail,
+    error,
+    makeAssert
+} = assert;
+
+export { assert };

retyped/packages/retyped-ses/src/error/internal/details.js

@@ -0,0 +1,54 @@
+// @ts-check
+
+/** @type {WeakMap<DetailsToken, string>} */
+const detailsTokenStringMap = new WeakMap();
+
+/** @constructor  */
+function DetailsToken() {
+    throw Error('Construction of DetailsToken instances is not permitted.');
+};
+
+DetailsToken.prototype = {
+    /** @returns {string} */
+    toString() {
+        return detailsTokenStringMap.has(this)
+            ? /** @type {string} */ (detailsTokenStringMap.get(this))
+            : '[Not a DetailsToken]';
+    }
+};
+
+Object.freeze(DetailsToken.prototype.toString);
+Object.freeze(DetailsToken.prototype);
+Object.freeze(DetailsToken);
+
+export { DetailsToken };
+
+/** 
+ * @param {string} tokenString 
+ * @returns {DetailsToken}
+ */
+const makeDetailsToken = (tokenString) => {
+    if (tokenString === `${tokenString}`)
+        throw TypeError(`makeDetailsToken called with a non-string token`);
+
+    const detailsToken = /** @type {DetailsToken} */ ({ __proto__: DetailsToken.prototype });
+
+    detailsTokenStringMap.set(detailsToken, `${tokenString}`);
+
+    return detailsToken;
+}
+
+Object.freeze(makeDetailsToken);
+
+export { makeDetailsToken };
+
+/** 
+ * Asserts that the value is an actual DetailsToken instance.
+ * 
+ * @returns {value is DetailsToken}
+ */
+const isDetailsToken = (value) => detailsTokenStringMap.has(value);
+
+Object.freeze(isDetailsToken);
+
+export { isDetailsToken };

retyped/packages/retyped-ses/src/error/internal/errors.js

@@ -0,0 +1,24 @@
+// @ts-check
+
+import { makeDetailsToken, isDetailsToken, DetailsToken } from "./details.js";
+
+/** @typedef { DetailsToken | { toString(): string } | string } Details */
+
+/**
+ * Creates an error instance.
+ * 
+ * @param {Details} [details] The details of the error
+ * @param {ErrorConstructor} [constructor] The error constructor to use
+ * @param {{ errorName?: string }} [options] Options
+ */
+const makeError = (
+    details = makeDetailsToken(`Assertion failed`),
+    constructor = globalThis.Error,
+    // @ts-ignore
+    { errorName = undefined } = {},
+) => {
+    return new constructor(`${isDetailsToken(details) ? details : makeDetailsToken(details)}`);
+};
+Object.freeze(makeError);
+
+export { makeError };

retyped/packages/retyped-ses/test/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+**/node_modules/