export ERTP types and normalize enum pattern (#10263)

refs: #4560

## Description

Exports ERTP types from the package entrypoint.

Establishes a pattern for constant enums so the type name matches.

Review by commit

### Security Considerations
none

### Scaling Considerations
none

### Documentation Considerations
none

### Testing Considerations


### Upgrade Considerations

docs/typescript.md

@@ -39,8 +39,8 @@ export {};
 **types-index.d.ts**
 ```ts
 // Export all the types this package provides
-export * from './types.js';
-export * from './other-types.js';
+export type * from './types.js';
+export type * from './other-types.js';
 ```
 
 The actual type implementation is then written in `types.ts` and `other-types.ts` files (per the example above).

packages/ERTP/src/amountMath.js

@@ -9,29 +9,26 @@ import { copyBagMathHelpers } from './mathHelpers/copyBagMathHelpers.js';
 
 /**
  * @import {CopyBag, CopySet} from '@endo/patterns';
- * @import {Amount, AssetKind, AmountValue, AssetKindForValue, AssetValueForKind, Brand, CopyBagAmount, CopySetAmount, MathHelpers, NatAmount, NatValue, SetAmount, SetValue} from './types.js';
+ * @import {Amount, AssetValueForKind, Brand, CopyBagAmount, CopySetAmount, MathHelpers, NatAmount, NatValue, SetAmount, SetValue} from './types.js';
  */
 
+// NB: AssetKind is both a constant for enumerated values and a type for those values.
 /**
  * Constants for the kinds of assets we support.
  *
- * @type {{
- *   NAT: 'nat';
- *   SET: 'set';
- *   COPY_SET: 'copySet';
- *   COPY_BAG: 'copyBag';
- * }}
+ * @enum {(typeof AssetKind)[keyof typeof AssetKind]}
  */
-const AssetKind = harden({
+export const AssetKind = /** @type {const} */ ({
   NAT: 'nat',
   SET: 'set',
   COPY_SET: 'copySet',
   COPY_BAG: 'copyBag',
 });
+harden(AssetKind);
 const assetKindNames = harden(Object.values(AssetKind).sort());
 
 /** @param {AssetKind} allegedAK */
-const assertAssetKind = allegedAK => {
+export const assertAssetKind = allegedAK => {
   assetKindNames.includes(allegedAK) ||
     Fail`The assetKind ${allegedAK} must be one of ${q(assetKindNames)}`;
 };
@@ -192,7 +189,7 @@ const isGTE = (leftAmount, rightAmount, brand = undefined) => {
  * and payments. They can be used to represent things like currency, stock, and
  * the abstract right to participate in a particular exchange.
  */
-const AmountMath = {
+export const AmountMath = {
   // TODO use overloading to handle when Brand has an AssetKind and when it doesn't.
   // a AmountForValue utility could help DRY those cases.
   /**
@@ -387,11 +384,9 @@ const AmountMath = {
 harden(AmountMath);
 
 /** @param {Amount} amount */
-const getAssetKind = amount => {
+export const getAssetKind = amount => {
   assertRecord(amount, 'amount');
   const { value } = amount;
   return assertValueGetAssetKind(value);
 };
 harden(getAssetKind);
-
-export { AmountMath, AssetKind, getAssetKind, assertAssetKind };

packages/ERTP/src/index.js

@@ -11,3 +11,6 @@ export * from './typeGuards.js';
  *
  * @import {Baggage} from '@agoric/vat-data'
  */
+
+// eslint-disable-next-line import/export
+export * from './types-index.js';

packages/ERTP/src/types-index.d.ts

@@ -1,2 +1,2 @@
 // Export all the types this package provides
-export * from './types.js';
+export type * from './types.js';

packages/ERTP/src/types.ts

@@ -3,6 +3,9 @@ import type { LatestTopic } from '@agoric/notifier';
 import type { ERef } from '@endo/far';
 import type { RemotableObject } from '@endo/pass-style';
 import type { CopyBag, CopySet, Key, Pattern } from '@endo/patterns';
+import type { AssetKind } from './amountMath.js';
+
+export type { AssetKind } from './amountMath.js';
 
 export type NatAmount = {
   brand: Brand<'nat'>;
@@ -75,7 +78,6 @@ export type AmountValue =
  * See doc-comment
  *   for `AmountValue`.
  */
-export type AssetKind = 'nat' | 'set' | 'copySet' | 'copyBag';
 export type AssetValueForKind<
   K extends AssetKind,
   M extends Key = Key,

packages/async-flow/src/types-index.d.ts

@@ -1,2 +1,2 @@
 // Export all the types this package provides
-export * from './types.js';
+export type * from './types.js';

packages/boot/tools/supports.ts

@@ -10,10 +10,9 @@ import { inspect } from 'util';
 import { buildSwingset } from '@agoric/cosmic-swingset/src/launch-chain.js';
 import {
   BridgeId,
+  makeTracer,
   NonNullish,
   VBankAccount,
-  makeTracer,
-  type BridgeIdValue,
   type Remote,
 } from '@agoric/internal';
 import { unmarshalFromVstorage } from '@agoric/internal/src/marshal.js';
@@ -23,11 +22,11 @@ import { initSwingStore } from '@agoric/swing-store';
 import { loadSwingsetConfigFile } from '@agoric/swingset-vat';
 import { makeSlogSender } from '@agoric/telemetry';
 import { TimeMath, Timestamp } from '@agoric/time';
-import { Fail } from '@endo/errors';
 import {
   fakeLocalChainBridgeTxMsgHandler,
   LOCALCHAIN_DEFAULT_ADDRESS,
 } from '@agoric/vats/tools/fake-bridge.js';
+import { Fail } from '@endo/errors';
 
 import {
   makeRunUtils,
@@ -43,7 +42,7 @@ import type { ExecutionContext as AvaT } from 'ava';
 import type { CoreEvalSDKType } from '@agoric/cosmic-proto/swingset/swingset.js';
 import type { EconomyBootstrapPowers } from '@agoric/inter-protocol/src/proposals/econ-behaviors.js';
 import type { SwingsetController } from '@agoric/swingset-vat/src/controller/controller.js';
-import type { BridgeHandler, IBCMethod, IBCPacket } from '@agoric/vats';
+import type { BridgeHandler, IBCMethod } from '@agoric/vats';
 import type { BootstrapRootObject } from '@agoric/vats/src/core/lib-boot.js';
 import type { EProxy } from '@endo/eventual-send';
 import { icaMocks, protoMsgMockMap, protoMsgMocks } from './ibc/mocks.js';
@@ -370,9 +369,9 @@ export const makeSwingsetTestKit = async (
     return msg.packet;
   };
 
-  const inboundQueue: [bridgeId: BridgeIdValue, arg1: unknown][] = [];
+  const inboundQueue: [bridgeId: BridgeId, arg1: unknown][] = [];
   /** Add a message that will be sent to the bridge by flushInboundQueue. */
-  const pushInbound = (bridgeId: BridgeIdValue, arg1: unknown) => {
+  const pushInbound = (bridgeId: BridgeId, arg1: unknown) => {
     inboundQueue.push([bridgeId, arg1]);
   };
   /**
@@ -629,7 +628,7 @@ export const makeSwingsetTestKit = async (
       console.log('🧻');
       return i;
     },
-    async runInbound(bridgeId: BridgeIdValue, msg: unknown) {
+    async runInbound(bridgeId: BridgeId, msg: unknown) {
       await runUtils.queueAndRun(() => inbound(bridgeId, msg), true);
     },
   };

packages/governance/src/constants.js

@@ -4,8 +4,9 @@
  * UNKNOWN is an escape hatch for types we haven't added yet. If you are
  * developing a new contract and use UNKNOWN, please also file an issue to ask
  * us to support the new type.
+ * @enum {typeof ParamType[keyof typeof ParamType]}
  */
-export const ParamTypes = /** @type {const} */ ({
+export const ParamType = /** @type {const} */ ({
   AMOUNT: 'amount',
   BRAND: 'brand',
   INSTALLATION: 'installation',
@@ -19,6 +20,8 @@ export const ParamTypes = /** @type {const} */ ({
   RELATIVE_TIME: 'relativeTime',
   UNKNOWN: 'unknown',
 });
+harden(ParamType);
 
-harden(ParamTypes);
-/** @typedef {typeof ParamTypes[keyof typeof ParamTypes]} ParamType */
+// For backwards compatibility
+// Shallow copy to work around TS d.ts defining an empty namespace instead of an object
+export const ParamTypes = { ...ParamType };

packages/inter-protocol/src/auction/scheduler.js

@@ -113,7 +113,7 @@ export const makeScheduler = async (
 
   const stepCancelToken = makeCancelToken();
 
-  /** @type {(typeof AuctionState)[keyof typeof AuctionState]} */
+  /** @type {AuctionState} */
   let auctionState = AuctionState.WAITING;
 
   /**

packages/inter-protocol/src/auction/util.js

@@ -12,12 +12,13 @@ import { Far } from '@endo/marshal';
 /**
  * Constants for Auction State.
  *
- * @type {{ ACTIVE: 'active'; WAITING: 'waiting' }}
+ * @enum {(typeof AuctionState)[keyof typeof AuctionState]}
  */
-export const AuctionState = {
+export const AuctionState = /** @type {const} */ ({
   ACTIVE: 'active',
   WAITING: 'waiting',
-};
+});
+harden(AuctionState);
 
 /**
  * @param {{ brand: Brand; value: Pattern }} numeratorAmountShape

packages/inter-protocol/src/vaultFactory/vault.js

@@ -52,6 +52,8 @@ const trace = makeTracer('Vault', true);
  * - CLOSED - vault was closed by the user and all assets have been paid out
  * - LIQUIDATED - vault was closed by the manager, with remaining assets paid to
  *   owner
+ *
+ * @enum {(typeof Phase)[keyof typeof Phase]}
  */
 export const Phase = /** @type {const} */ ({
   ACTIVE: 'active',
@@ -60,9 +62,10 @@ export const Phase = /** @type {const} */ ({
   LIQUIDATED: 'liquidated',
   TRANSFER: 'transfer',
 });
+harden(Phase);
 
 /**
- * @typedef {Phase[keyof Omit<typeof Phase, 'TRANSFER'>]} VaultPhase
+ * @typedef {Exclude<Phase, 'transfer'>} VaultPhase
  * @type {{ [K in VaultPhase]: VaultPhase[] }}
  */
 const validTransitions = {
@@ -73,13 +76,11 @@ const validTransitions = {
 };
 
 /**
- * @typedef {Phase[keyof typeof Phase]} HolderPhase
- *
  * @typedef {object} VaultNotification
  * @property {Amount<'nat'>} locked Amount of Collateral locked
  * @property {{ debt: Amount<'nat'>; interest: Ratio }} debtSnapshot 'debt' at
  *   the point the compounded interest was 'interest'
- * @property {HolderPhase} vaultState
+ * @property {Phase} vaultState
  */
 
 // XXX masks typedef from types.js, but using that causes circular def problems
@@ -341,7 +342,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
             )} for ${q(collateralAmount)} collateral`;
         },
 
-        /** @param {HolderPhase} newPhase */
+        /** @param {Phase} newPhase */
         getStateSnapshot(newPhase) {
           const { state, facets } = this;
 

packages/internal/src/config.js

@@ -15,6 +15,8 @@
 
 /**
  * Event source ids used by the bridge device.
+ *
+ * @enum {(typeof BridgeId)[keyof typeof BridgeId]}
  */
 export const BridgeId = /** @type {const} */ ({
   BANK: 'bank',
@@ -28,7 +30,6 @@ export const BridgeId = /** @type {const} */ ({
   WALLET: 'wallet',
 });
 harden(BridgeId);
-/** @typedef {(typeof BridgeId)[keyof typeof BridgeId]} BridgeIdValue */
 
 export const CosmosInitKeyToBridgeId = {
   vbankPort: BridgeId.BANK,

packages/internal/src/types-index.d.ts

@@ -1 +1 @@
-export * from './types.js';
+export type * from './types.js';

packages/network/src/network.js

@@ -404,12 +404,13 @@ const prepareInboundAttempt = (zone, makeConnection, { watch, finalizer }) => {
   return makeInboundAttempt;
 };
 
-/** @enum {number} */
+/** @enum {typeof RevokeState[keyof typeof RevokeState]} */
 const RevokeState = /** @type {const} */ ({
   NOT_REVOKED: 0,
   REVOKING: 1,
   REVOKED: 2,
 });
+harden(RevokeState);
 
 /**
  * @param {import('@agoric/zone').Zone} zone

packages/notifier/src/types-index.d.ts

@@ -1,2 +1,2 @@
 // Export all the types this package provides
-export * from './types.js';
+export type * from './types.js';

packages/orchestration/src/types-index.d.ts

@@ -1 +1 @@
-export * from './types.js';
+export type * from './types.js';

packages/smart-wallet/src/types-index.d.ts

@@ -1,2 +1,2 @@
 // Export all the types this package provides
-export * from './types.js';
+export type * from './types.js';

packages/swingset-liveslots/src/types-index.d.ts

@@ -1,4 +1,4 @@
 // Export all the types this package provides
 // eslint-disable-next-line import/export
-export * from './types.js';
-export * from './vatDataTypes.js';
+export type * from './types.js';
+export type * from './vatDataTypes.js';

packages/time/src/types-index.d.ts

@@ -1 +1 @@
-export * from './types.js';
+export type * from './types.js';

packages/vats/src/bridge-target.js

@@ -173,7 +173,7 @@ export const prepareBridgeTargetKit = (zone, makeTargetRegistration) =>
       targetRegistry: TargetRegistryI,
     },
     /**
-     * @template {import('@agoric/internal').BridgeIdValue} T
+     * @template {import('@agoric/internal').BridgeId} T
      * @param {import('./types').ScopedBridgeManager<T>} manager
      * @param {string} inboundEventType
      * @param {AppTransformer} [appTransformer]

packages/vats/src/bridge.js

@@ -10,7 +10,7 @@ import { E } from '@endo/far';
  * loses the function's genericity. If `register` was async, we could use its
  * type directly, and it would remain generic.
  *
- * @template {import('@agoric/internal').BridgeIdValue} BridgeId
+ * @template {import('@agoric/internal').BridgeId} BridgeId
  * @param {ERef<import('./types.js').BridgeManager>} bridgeManager
  * @param {BridgeId} bridgeIdValue
  * @param {import('@agoric/internal').Remote<

packages/vats/src/types-index.d.ts

@@ -1,2 +1,2 @@
 // eslint-disable-next-line import/export -- no named exports
-export * from './types.js';
+export type * from './types.js';

packages/vats/src/types.ts

@@ -1,6 +1,6 @@
 /* eslint-disable no-use-before-define */
 import type { FungibleTokenPacketData } from '@agoric/cosmic-proto/ibc/applications/transfer/v2/packet.js';
-import type { BridgeIdValue, Remote } from '@agoric/internal';
+import type { BridgeId, Remote } from '@agoric/internal';
 import type { Bytes } from '@agoric/network';
 import type { Guarded } from '@endo/exo';
 import type { PacketSDKType } from '@agoric/cosmic-proto/ibc/core/channel/v1/channel.js';
@@ -105,13 +105,13 @@ export type BridgeHandler = {
   fromBridge: (obj: any) => Promise<unknown>;
 };
 
-export type ScopedBridgeManagerMethods<BridgeId extends BridgeIdValue> = {
+export type ScopedBridgeManagerMethods<B extends BridgeId> = {
   /**
    * Optional bridge ID getter. Not part of the production bridge vat but
    * available in fake bridges as a means for test reflection and for the type
    * system to hang the bridgeId
    */
-  getBridgeId?: () => BridgeId;
+  getBridgeId?: () => B;
   /** Downcall from the VM into Golang */
   toBridge: (obj: any) => Promise<any>;
   /** Upcall from Golang into the VM */
@@ -121,16 +121,16 @@ export type ScopedBridgeManagerMethods<BridgeId extends BridgeIdValue> = {
 };
 
 /** An object which handles messages for a specific bridge */
-export type ScopedBridgeManager<BridgeId extends BridgeIdValue> = Guarded<
-  ScopedBridgeManagerMethods<BridgeId>
+export type ScopedBridgeManager<B extends BridgeId> = Guarded<
+  ScopedBridgeManagerMethods<B>
 >;
 
 /** The object to manage this bridge */
 export type BridgeManager = {
-  register: <BridgeId extends BridgeIdValue>(
-    bridgeId: BridgeId,
+  register: <B extends BridgeId>(
+    bridgeId: B,
     handler?: Remote<BridgeHandler>,
-  ) => ScopedBridgeManager<BridgeId>;
+  ) => ScopedBridgeManager<B>;
 };
 
 export type IBCPortID = string;

packages/vats/src/vat-transfer.js

@@ -33,7 +33,7 @@ export const buildRootObject = (_vatPowers, _args, baggage) => {
   const managerToKits = zone.weakMapStore('managerToHandler');
   return Far('TransferVat', {
     /**
-     * @template {import('@agoric/internal').BridgeIdValue} T
+     * @template {import('@agoric/internal').BridgeId} T
      * @param {import('./types').ScopedBridgeManager<T>} manager
      * @param {string} [inboundType]
      * @param {import('./bridge-target').AppTransformer} [appTransformer]

packages/vow/src/types-index.d.ts

@@ -1,5 +1,5 @@
 // Export all the types this package provides
-export * from './types.js';
+export type * from './types.js';
 
 // XXX re-exporting the Remote type for back-compat
-export { Remote } from '@agoric/internal/src/types.js';
+export type { Remote } from '@agoric/internal/src/types.js';