docs(patterns): consistent type constraints for makeExo

packages/store/src/patterns/exo-makers.js

@@ -47,15 +47,14 @@ export const initEmpty = () => emptyRecord;
  */
 
 /**
- * @template A args to init
- * @template S state from init
- * @template {Record<string | symbol, CallableFunction>} T methods
+ * @template {(...args: any[]) => any} I init function
+ * @template {Record<string | symbol, CallableFunction>} M methods
  * @param {string} tag
  * @param {any} interfaceGuard
- * @param {(...args: A[]) => S} init
- * @param {T & ThisType<{ self: T, state: S }>} methods
- * @param {FarClassOptions<Context<S,T>>} [options]
- * @returns {(...args: A[]) => (T & import('@endo/eventual-send').RemotableBrand<{}, T>)}
+ * @param {I} init
+ * @param {M & ThisType<{ self: M, state: ReturnType<I> }>} methods
+ * @param {FarClassOptions<Context<ReturnType<I>, M>>} [options]
+ * @returns {(...args: Parameters<I>) => (M & import('@endo/eventual-send').RemotableBrand<{}, M>)}
  */
 export const defineExoClass = (
   tag,
@@ -64,7 +63,7 @@ export const defineExoClass = (
   methods,
   { finish = undefined } = {},
 ) => {
-  /** @type {WeakMap<T,Context<S, T>>} */
+  /** @type {WeakMap<M,Context<ReturnType<I>, M>>} */
   const contextMap = new WeakMap();
   const prototype = defendPrototype(
     tag,
@@ -73,14 +72,17 @@ export const defineExoClass = (
     true,
     interfaceGuard,
   );
+  /**
+   * @param  {Parameters<I>} args
+   */
   const makeInstance = (...args) => {
     // Be careful not to freeze the state record
     const state = seal(init(...args));
-    /** @type {T} */
+    /** @type {M} */
     // @ts-expect-error could be instantiated with different subtype
     const self = harden({ __proto__: prototype });
     // Be careful not to freeze the state record
-    /** @type {Context<S,T>} */
+    /** @type {Context<ReturnType<I>,M>} */
     const context = freeze({ state, self });
     contextMap.set(self, context);
     if (finish) {
@@ -94,15 +96,14 @@ export const defineExoClass = (
 harden(defineExoClass);
 
 /**
- * @template A args to init
- * @template S state from init
- * @template {Record<string, Record<string | symbol, CallableFunction>>} F methods
+ * @template {(...args: any[]) => any} I init function
+ * @template {Record<string, Record<string | symbol, CallableFunction>>} F facet methods
  * @param {string} tag
  * @param {any} interfaceGuardKit
- * @param {(...args: A[]) => S} init
- * @param {F & ThisType<{ facets: F, state: S }> } methodsKit
- * @param {FarClassOptions<KitContext<S,F>>} [options]
- * @returns {(...args: A[]) => F}
+ * @param {I} init
+ * @param {F & ThisType<{ facets: F, state: ReturnType<I> }> } methodsKit
+ * @param {FarClassOptions<KitContext<ReturnType<I>,F>>} [options]
+ * @returns {(...args: Parameters<I>) => F}
  */
 export const defineExoClassKit = (
   tag,
@@ -119,6 +120,9 @@ export const defineExoClassKit = (
     true,
     interfaceGuardKit,
   );
+  /**
+   * @param {Parameters<I>} args
+   */
   const makeInstanceKit = (...args) => {
     // Be careful not to freeze the state record
     const state = seal(init(...args));
@@ -145,7 +149,7 @@ export const defineExoClassKit = (
 harden(defineExoClassKit);
 
 /**
- * @template {Record<string, Method>} T
+ * @template {Record<string | symbol, CallableFunction>} T
  * @param {string} tag
  * @param {InterfaceGuard | undefined} interfaceGuard CAVEAT: static typing does not yet support `callWhen` transformation
  * @param {T} methods

packages/store/test/test-heap-classes.js

@@ -106,6 +106,7 @@ test('test makeExo', t => {
   t.throws(() => upCounter.incr(-3), {
     message: 'In "incr" method of (upCounter): arg 0?: -3 - Must be >= 0',
   });
+  // @ts-expect-error deliberately bad arg for testing
   t.throws(() => upCounter.incr('foo'), {
     message:
       'In "incr" method of (upCounter): arg 0?: string "foo" - Must be a number',