fix(marshal): remove ambient types, generate declarations from JSDoc

packages/captp/src/captp.js

@@ -1,6 +1,9 @@
 // @ts-check
 /// <reference types="ses"/>
 
+/** @template Slot @typedef {import('@endo/marshal').ConvertValToSlot<Slot>} ConvertValToSlot */
+/** @template Slot @typedef {import('@endo/marshal').ConvertSlotToVal<Slot>} ConvertSlotToVal */
+
 // Your app may need to `import '@endo/eventual-send/shim.js'` to get HandledPromise
 
 // This logic was mostly lifted from @agoric/swingset-vat liveSlots.js

packages/captp/src/types.js

@@ -17,7 +17,7 @@
  */
 
 /**
- * @typedef {[boolean, CapData<CapTPSlot>]} TrapCompletion The head of the pair
+ * @typedef {[boolean, import('@endo/marshal').CapData<CapTPSlot>]} TrapCompletion The head of the pair
  * is the `isRejected` value indicating whether the sync call was an exception,
  * and tail of the pair is the serialized fulfillment value or rejection reason.
  * (The fulfillment value is a non-thenable.  The rejection reason is normally

packages/marshal/NEWS.md

@@ -1,5 +1,17 @@
 User-visible changes in `@endo/marshal`:
 
+# Next release
+
+Switch from ambient to exported types.
+Include type declarations (`.d.ts`) generated from JSDoc to avoid requiring
+dependents to parse `.js` files in their `node_modules`.
+
+In order to use the types from `@endo/marshal` you now need to import them
+explicitly. For example, to make them available in scope, use the following:
+- JSDoc: `/** @typedef {import('@endo/marshal').PassStyle} PassStyle */`
+- TypeScript: `import type { PassStyle } from '@endo/marshal'`
+
+
 # v0.5.3 (2021-01-27)
 
 Includes TypeScript definitions in published artifact.

packages/marshal/index.js

@@ -39,3 +39,6 @@ export {
   isRecord,
   isCopyArray,
 } from './src/typeGuards.js';
+
+// eslint-disable-next-line import/export
+export * from './src/types.js';

packages/marshal/jsconfig.build.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./jsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "declarationMap": true
+  },
+  "exclude": ["test/"]
+}

packages/marshal/package.json

@@ -9,6 +9,9 @@
   },
   "scripts": {
     "build": "exit 0",
+    "clean": "tsc --build jsconfig.build.json --clean",
+    "prepack": "tsc --build jsconfig.build.json",
+    "postpack": "yarn clean",
     "test": "ava",
     "test:c8": "c8 $C8_OPTIONS ava --config=ava-nesm.config.js",
     "test:xs": "exit 0",
@@ -47,9 +50,11 @@
   "files": [
     "LICENSE*",
     "SECURITY*",
+    "NEWS*",
     "src",
     "*.js",
-    "*.ts"
+    "*.ts",
+    "*.map"
   ],
   "eslintConfig": {
     "extends": [

packages/marshal/src/deeplyFulfilled.js

@@ -3,15 +3,14 @@
 /// <reference types="ses"/>
 
 import { E } from '@endo/eventual-send';
-/**
- * @template T
- * @typedef {import('@endo/eventual-send').ERef<T>} ERef
- */
 import { isPromise } from '@endo/promise-kit';
 import { getTag, isObject } from './helpers/passStyle-helpers.js';
 import { makeTagged } from './makeTagged.js';
 import { passStyleOf } from './passStyleOf.js';
 
+/** @typedef {import('./types.js').Passable} Passable */
+/** @template T @typedef {import('@endo/eventual-send').ERef<T>} ERef */
+
 const { details: X, quote: q } = assert;
 const { ownKeys } = Reflect;
 const { fromEntries } = Object;

packages/marshal/src/helpers/copyArray.js

@@ -2,8 +2,6 @@
 
 /// <reference types="ses"/>
 
-import '../types.js';
-import './internal-types.js';
 import { assertChecker, checkNormalProperty } from './passStyle-helpers.js';
 
 const { details: X } = assert;
@@ -13,7 +11,7 @@ const { isArray, prototype: arrayPrototype } = Array;
 
 /**
  *
- * @type {PassStyleHelper}
+ * @type {import('./internal-types.js').PassStyleHelper}
  */
 export const CopyArrayHelper = harden({
   styleName: 'copyArray',

packages/marshal/src/helpers/copyRecord.js

@@ -8,9 +8,6 @@ import {
   checkNormalProperty,
 } from './passStyle-helpers.js';
 
-import '../types.js';
-import './internal-types.js';
-
 const { details: X } = assert;
 const { ownKeys } = Reflect;
 const {
@@ -21,7 +18,7 @@ const {
 
 /**
  *
- * @type {PassStyleHelper}
+ * @type {import('./internal-types.js').PassStyleHelper}
  */
 export const CopyRecordHelper = harden({
   styleName: 'copyRecord',

packages/marshal/src/helpers/error.js

@@ -2,10 +2,10 @@
 
 /// <reference types="ses"/>
 
-import '../types.js';
-import './internal-types.js';
 import { assertChecker } from './passStyle-helpers.js';
 
+/** @typedef {import('./internal-types.js').PassStyleHelper} PassStyleHelper */
+
 const { details: X } = assert;
 const { getPrototypeOf, getOwnPropertyDescriptors } = Object;
 const { ownKeys } = Reflect;

packages/marshal/src/helpers/internal-types.js

@@ -2,6 +2,12 @@
 
 /// <reference path="../extra-types.d.ts" />
 
+export {};
+
+/** @typedef {import('../types.js').Checker} Checker */
+/** @typedef {import('../types.js').PassStyle} PassStyle */
+/** @typedef {import('../types.js').PassStyleOf} PassStyleOf */
+
 /**
  * The PassStyleHelper are only used to make a `passStyleOf` function.
  * Thus, it should not depend on an ambient one. Rather, each helper should be

packages/marshal/src/helpers/passStyle-helpers.js

@@ -2,8 +2,8 @@
 
 /// <reference types="ses"/>
 
-import '../types.js';
-import './internal-types.js';
+/** @typedef {import('../types.js').Checker} Checker */
+/** @typedef {import('../types.js').PassStyle} PassStyle */
 
 const { details: X, quote: q } = assert;
 const {

packages/marshal/src/helpers/remotable.js

@@ -2,8 +2,6 @@
 
 /// <reference types="ses"/>
 
-import '../types.js';
-import './internal-types.js';
 import {
   assertChecker,
   canBeMethod,
@@ -15,6 +13,12 @@ import {
 } from './passStyle-helpers.js';
 import { getEnvironmentOption } from './environment-options.js';
 
+/** @typedef {import('../types.js').Checker} Checker */
+/** @typedef {import('../types.js').InterfaceSpec} InterfaceSpec */
+/** @typedef {import('../types.js').MarshalGetInterfaceOf} MarshalGetInterfaceOf */
+/** @typedef {import('./internal-types.js').PassStyleHelper} PassStyleHelper */
+/** @typedef {import('../types.js').Remotable} Remotable */
+
 const { details: X, quote: q } = assert;
 const { ownKeys } = Reflect;
 const { prototype: functionPrototype } = Function;

packages/marshal/src/helpers/tagged.js

@@ -9,16 +9,13 @@ import {
   checkNormalProperty,
 } from './passStyle-helpers.js';
 
-import '../types.js';
-import './internal-types.js';
-
 const { details: X } = assert;
 const { ownKeys } = Reflect;
 const { getPrototypeOf, prototype: objectPrototype } = Object;
 
 /**
  *
- * @type {PassStyleHelper}
+ * @type {import('./internal-types.js').PassStyleHelper}
  */
 export const TaggedHelper = harden({
   styleName: 'tagged',

packages/marshal/src/make-far.js

@@ -10,6 +10,8 @@ import {
 } from './helpers/remotable.js';
 import { pureCopy } from './pureCopy.js';
 
+/** @typedef {import('./types.js').InterfaceSpec} InterfaceSpec */
+
 const { quote: q, details: X } = assert;
 
 const { prototype: functionPrototype } = Function;
@@ -81,8 +83,8 @@ const assertCanBeRemotable = candidate =>
  * Carol's `iface` as misrepresented by VatA.
  * @param {undefined} [props=undefined] Currently may only be undefined.
  * That plan is that own-properties are copied to the remotable
- * @param {object} [remotable={}] The object used as the remotable
- * @returns {object} remotable, modified for debuggability
+ * @param {any} [remotable={}] The object used as the remotable
+ * @returns {any} remotable, modified for debuggability
  */
 export const Remotable = (
   iface = 'Remotable',

packages/marshal/src/marshal-justin.js

@@ -5,11 +5,12 @@
 import { Nat } from '@endo/nat';
 import { QCLASS } from './marshal.js';
 
-import './types.js';
 import { getErrorConstructor } from './helpers/error.js';
 import { isObject } from './helpers/passStyle-helpers.js';
 import { AtAtPrefixPattern, passableSymbolForName } from './helpers/symbol.js';
 
+/** @typedef {import('./types.js').Encoding} Encoding */
+
 const { ownKeys } = Reflect;
 const { isArray } = Array;
 const { stringify: quote } = JSON;

packages/marshal/src/marshal-stringify.js

@@ -3,15 +3,15 @@
 
 import { makeMarshal } from './marshal.js';
 
-import './types.js';
+/** @typedef {import('./types.js').OnlyData} OnlyData */
 
 const { details: X } = assert;
 
-/** @type {ConvertValToSlot<any>} */
+/** @type {import('./types.js').ConvertValToSlot<any>} */
 const doNotConvertValToSlot = val =>
   assert.fail(X`Marshal's stringify rejects presences and promises ${val}`);
 
-/** @type {ConvertSlotToVal<any>} */
+/** @type {import('./types.js').ConvertSlotToVal<any>} */
 const doNotConvertSlotToVal = (slot, _iface) =>
   assert.fail(X`Marshal's parse must not encode any slots ${slot}`);
 

packages/marshal/src/marshal.js

@@ -5,7 +5,6 @@
 import { Nat } from '@endo/nat';
 import { assertPassable, passStyleOf } from './passStyleOf.js';
 
-import './types.js';
 import { getInterfaceOf } from './helpers/remotable.js';
 import { ErrorHelper, getErrorConstructor } from './helpers/error.js';
 import { makeTagged } from './makeTagged.js';
@@ -16,6 +15,15 @@ import {
   passableSymbolForName,
 } from './helpers/symbol.js';
 
+/** @typedef {import('./types.js').MakeMarshalOptions} MakeMarshalOptions */
+/** @template Slot @typedef {import('./types.js').ConvertSlotToVal<Slot>} ConvertSlotToVal */
+/** @template Slot @typedef {import('./types.js').ConvertValToSlot<Slot>} ConvertValToSlot */
+/** @template Slot @typedef {import('./types.js').Serialize<Slot>} Serialize */
+/** @template Slot @typedef {import('./types.js').Unserialize<Slot>} Unserialize */
+/** @typedef {import('./types.js').Passable} Passable */
+/** @typedef {import('./types.js').InterfaceSpec} InterfaceSpec */
+/** @typedef {import('./types.js').Encoding} Encoding */
+
 const { ownKeys } = Reflect;
 const { isArray } = Array;
 const {
@@ -34,14 +42,18 @@ const { details: X, quote: q } = assert;
 const QCLASS = '@qclass';
 export { QCLASS };
 
+/** @type {ConvertValToSlot<any>} */
 const defaultValToSlotFn = x => x;
+/** @type {ConvertSlotToVal<any>} */
 const defaultSlotToValFn = (x, _) => x;
 
 /**
  * @template Slot
- * @type {MakeMarshal<Slot>}
+ * @param {ConvertValToSlot<Slot>} [convertValToSlot]
+ * @param {ConvertSlotToVal<Slot>} [convertSlotToVal]
+ * @param {MakeMarshalOptions} [options]
  */
-export function makeMarshal(
+export const makeMarshal = (
   convertValToSlot = defaultValToSlotFn,
   convertSlotToVal = defaultSlotToValFn,
   {
@@ -55,7 +67,7 @@ export function makeMarshal(
     marshalSaveError = err =>
       console.log('Temporary logging of sent error', err),
   } = {},
-) {
+) => {
   assert.typeof(marshalName, 'string');
   assert(
     errorTagging === 'on' || errorTagging === 'off',
@@ -67,7 +79,6 @@ export function makeMarshal(
   };
 
   /**
-   * @template Slot
    * @type {Serialize<Slot>}
    */
   const serialize = root => {
@@ -482,7 +493,6 @@ export function makeMarshal(
   };
 
   /**
-   * @template Slot
    * @type {Unserialize<Slot>}
    */
   const unserialize = data => {
@@ -507,4 +517,4 @@ export function makeMarshal(
     serialize,
     unserialize,
   });
-}
+};

packages/marshal/src/passStyleOf.js

@@ -11,10 +11,14 @@ import { TaggedHelper } from './helpers/tagged.js';
 import { RemotableHelper } from './helpers/remotable.js';
 import { ErrorHelper } from './helpers/error.js';
 
-import './types.js';
-import './helpers/internal-types.js';
 import { assertPassableSymbol } from './helpers/symbol.js';
 
+/** @typedef {import('./helpers/internal-types.js').PassStyleHelper} PassStyleHelper */
+/** @typedef {import('./types.js').Passable} Passable */
+/** @typedef {import('./types.js').PassStyle} PassStyle */
+/** @typedef {import('./types.js').PassStyleOf} PassStyleOf */
+/** @typedef {import('./types.js').PrimitiveStyle} PrimitiveStyle */
+
 /** @typedef {Exclude<PassStyle, PrimitiveStyle | "promise">} HelperPassStyle */
 
 const { details: X, quote: q } = assert;

packages/marshal/src/pureCopy.js

@@ -4,6 +4,9 @@ import { getTag } from './helpers/passStyle-helpers.js';
 import { makeTagged } from './makeTagged.js';
 import { passStyleOf } from './passStyleOf.js';
 
+/** @typedef {import('./types.js').OnlyData} OnlyData */
+/** @typedef {import('./types.js').CopyTagged} CopyTagged */
+
 const { is } = Object;
 const { details: X, quote: q } = assert;
 

packages/marshal/src/typeGuards.js

@@ -2,6 +2,11 @@
 
 import { passStyleOf } from './passStyleOf.js';
 
+/** @typedef {import('./types.js').Passable} Passable */
+/** @template T @typedef {import('./types.js').CopyArray<T>} CopyArray */
+/** @template T @typedef {import('./types.js').CopyRecord<T>} CopyRecord */
+/** @typedef {import('./types.js').Remotable} Remotable */
+
 const { details: X, quote: q } = assert;
 
 /**