refactor: explicitly mark the items which should not be visible externally as internal

Author: boblat

package.json

@@ -15,9 +15,8 @@
     "build:1-lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\" --max-warnings 0",
     "build:2-check-types": "tsc -p tsconfig.json",
     "build:3-build": "rollup -c --configPlugin typescript",
-    "build:4-remove-internal-types": "rimraf -g dist/impl/*.d.ts dist/impl/**/*.d.ts dist/internal/*.d.ts",
-    "build:5-copy-pkg-json": "tstk copy-package-json -c",
-    "build:6-copy-readme": "copyfiles ./README.md ./dist",
+    "build:4-copy-pkg-json": "tstk copy-package-json -c",
+    "build:5-copy-readme": "copyfiles ./README.md ./dist",
     "watch": "rollup -c -w --configPlugin typescript",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",

src/abi-metadata.ts

@@ -6,6 +6,7 @@ import type { TypeInfo } from './impl/encoded-types'
 import { getArc4TypeName } from './impl/encoded-types'
 import type { DeliberateAny } from './typescript-helpers'
 
+/** @internal */
 export interface AbiMetadata {
   methodName: string
   name?: string
@@ -18,6 +19,7 @@ export interface AbiMetadata {
 }
 
 const metadataStore: WeakMap<{ new (): Contract }, Record<string, AbiMetadata>> = new WeakMap()
+/** @internal */
 export const attachAbiMetadata = (contract: { new (): Contract }, methodName: string, metadata: AbiMetadata): void => {
   if (!metadataStore.has(contract)) {
     metadataStore.set(contract, {})
@@ -31,6 +33,7 @@ export const attachAbiMetadata = (contract: { new (): Contract }, methodName: st
   }
 }
 
+/** @internal */
 export const getContractAbiMetadata = <T extends Contract>(contract: T | { new (): T }): Record<string, AbiMetadata> => {
   // Initialize result object to store merged metadata
   const result: Record<string, AbiMetadata> = {}
@@ -63,11 +66,13 @@ export const getContractAbiMetadata = <T extends Contract>(contract: T | { new (
   return result
 }
 
+/** @internal */
 export const getContractMethodAbiMetadata = <T extends Contract>(contract: T | { new (): T }, methodName: string): AbiMetadata => {
   const metadatas = getContractAbiMetadata(contract)
   return metadatas[methodName]
 }
 
+/** @internal */
 export const getArc4Signature = (metadata: AbiMetadata): string => {
   if (metadata.methodSignature === undefined) {
     const argTypes = metadata.argTypes.map((t) => JSON.parse(t) as TypeInfo).map((t) => getArc4TypeName(t, metadata.resourceEncoding, 'in'))
@@ -77,6 +82,7 @@ export const getArc4Signature = (metadata: AbiMetadata): string => {
   return metadata.methodSignature
 }
 
+/** @internal */
 export const getArc4Selector = (metadata: AbiMetadata): Uint8Array => {
   const hash = js_sha512.sha512_256.array(getArc4Signature(metadata))
   return new Uint8Array(hash.slice(0, 4))

src/collections/custom-key-map.ts

@@ -1,6 +1,5 @@
-import type { Account } from '@algorandfoundation/algorand-typescript'
+import type { Account, BytesCompat, Uint64Compat } from '@algorandfoundation/algorand-typescript'
 import { InternalError } from '../errors'
-import type { StubBytesCompat, StubUint64Compat } from '../impl/primitives'
 import type { DeliberateAny } from '../typescript-helpers'
 import { asBytesCls, asUint64Cls } from '../util'
 
@@ -75,13 +74,13 @@ export class AccountMap<TValue> extends CustomKeyMap<Account, TValue> {
   }
 }
 
-export class BytesMap<TValue> extends CustomKeyMap<StubBytesCompat, TValue> {
+export class BytesMap<TValue> extends CustomKeyMap<BytesCompat, TValue> {
   constructor() {
     super((bytes) => asBytesCls(bytes).valueOf())
   }
 }
 
-export class Uint64Map<TValue> extends CustomKeyMap<StubUint64Compat, TValue> {
+export class Uint64Map<TValue> extends CustomKeyMap<Uint64Compat, TValue> {
   constructor() {
     super((uint64) => asUint64Cls(uint64).valueOf())
   }

src/constants.ts

@@ -1,25 +1,45 @@
 import { Bytes, FixedBytes } from './impl/primitives'
 
+/** @internal */
 export const UINT64_SIZE = 64
+/** @internal */
 export const UINT512_SIZE = 512
+/** @internal */
 export const MAX_UINT8 = 2 ** 8 - 1
+/** @internal */
 export const MAX_UINT16 = 2 ** 16 - 1
+/** @internal */
 export const MAX_UINT32 = 2 ** 32 - 1
+/** @internal */
 export const MAX_UINT64 = 2n ** 64n - 1n
+/** @internal */
 export const MAX_UINT128 = 2n ** 128n - 1n
+/** @internal */
 export const MAX_UINT256 = 2n ** 256n - 1n
+/** @internal */
 export const MAX_UINT512 = 2n ** 512n - 1n
+/** @internal */
 export const MAX_BYTES_SIZE = 4096
+/** @internal */
 export const MAX_LOG_SIZE = 1024
+/** @internal */
 export const MAX_ITEMS_IN_LOG = 32
+/** @internal */
 export const MAX_BOX_SIZE = 32768
+/** @internal */
 export const BITS_IN_BYTE = 8
+/** @internal */
 export const DEFAULT_ACCOUNT_MIN_BALANCE = 100_000
+/** @internal */
 export const DEFAULT_MAX_TXN_LIFE = 1_000
+/** @internal */
 export const DEFAULT_ASSET_CREATE_MIN_BALANCE = 1000_000
+/** @internal */
 export const DEFAULT_ASSET_OPT_IN_MIN_BALANCE = 10_000
 
-// from python code: list(b"\x85Y\xb5\x14x\xfd\x89\xc1vC\xd0]\x15\xa8\xaek\x10\xabG\xbbm\x8a1\x88\x11V\xe6\xbd;\xae\x95\xd1")
+/** @internal
+ * from python code: list(b"\x85Y\xb5\x14x\xfd\x89\xc1vC\xd0]\x15\xa8\xaek\x10\xabG\xbbm\x8a1\x88\x11V\xe6\xbd;\xae\x95\xd1")
+ */
 export const DEFAULT_GLOBAL_GENESIS_HASH = FixedBytes(
   32,
   new Uint8Array([
@@ -28,37 +48,55 @@ export const DEFAULT_GLOBAL_GENESIS_HASH = FixedBytes(
   ]),
 )
 
-// algorand encoded address of 32 zero bytes
+/** @internal
+ * algorand encoded address of 32 zero bytes
+ */
 export const ZERO_ADDRESS = Bytes.fromBase32('AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA')
 
-/**
+/** @internal
 "\x09"  # pragma version 9
 "\x81\x01"  # pushint 1
  */
 export const ALWAYS_APPROVE_TEAL_PROGRAM = Bytes(new Uint8Array([0x09, 0x81, 0x01]))
 
-// bytes: program (logic) data prefix when signing
+/** @internal
+ * bytes: program (logic) data prefix when signing
+ */
 export const LOGIC_DATA_PREFIX = Bytes('ProgData')
 
-//number: minimum transaction fee
+/** @internal
+ * number: minimum transaction fee
+ */
 export const MIN_TXN_FEE = 1000
 
+/** @internal */
 export const ABI_RETURN_VALUE_LOG_PREFIX = Bytes.fromHex('151F7C75')
 
+/** @internal */
 export const UINT64_OVERFLOW_UNDERFLOW_MESSAGE = 'Uint64 overflow or underflow'
+/** @internal */
 export const BIGUINT_OVERFLOW_UNDERFLOW_MESSAGE = 'BigUint overflow or underflow'
+/** @internal */
 export const DEFAULT_TEMPLATE_VAR_PREFIX = 'TMPL_'
 
+/** @internal */
 export const APP_ID_PREFIX = 'appID'
+/** @internal */
 export const HASH_BYTES_LENGTH = 32
+/** @internal */
 export const ALGORAND_ADDRESS_BYTE_LENGTH = 36
+/** @internal */
 export const ALGORAND_CHECKSUM_BYTE_LENGTH = 4
+/** @internal */
 export const ALGORAND_ADDRESS_LENGTH = 58
 
+/** @internal */
 export const PROGRAM_TAG = 'Program'
 
+/** @internal */
 export const TRANSACTION_GROUP_MAX_SIZE = 16
 
+/** @internal */
 export enum OnApplicationComplete {
   NoOpOC = 0,
   OptInOC = 1,
@@ -68,6 +106,7 @@ export enum OnApplicationComplete {
   DeleteApplicationOC = 5,
 }
 
+/** @internal */
 export const ConventionalRouting = {
   methodNames: {
     closeOutOfApplication: 'closeOutOfApplication',

src/context-helpers/context-manager.ts

@@ -1,5 +1,6 @@
 import type { TestExecutionContext } from '../test-execution-context'
 
+/** @internal */
 export class ContextManager {
   private static _instance: TestExecutionContext | undefined
 

src/context-helpers/context-util.ts

@@ -5,6 +5,7 @@ import { AssertError } from '../errors'
 import { ApplicationCallTransaction } from '../impl/transactions'
 import { lazyContext } from './internal-context'
 
+/** @internal */
 export const checkRoutingConditions = (appId: uint64, metadata: AbiMetadata) => {
   const appData = lazyContext.getApplicationData(appId)
   const isCreating = appData.isCreating

src/context-helpers/internal-context.ts

@@ -65,7 +65,7 @@ class InternalContext {
   }
 
   getApplicationData(id: StubUint64Compat | BaseContract): ApplicationData {
-    const uint64Id = id instanceof BaseContract ? this.ledger.getApplicationForContract(id).id : Uint64Cls.fromCompat(id)
+    const uint64Id = id instanceof BaseContract ? this.ledger.getApplicationForContract(id).id : Uint64Cls.fromCompat(id).asAlgoTs()
     const data = this.ledger.applicationDataMap.get(uint64Id)
     if (!data) {
       throw new InternalError('Unknown application, check correct testing context is active')
@@ -82,4 +82,5 @@ class InternalContext {
   }
 }
 
+/** @internal */
 export const lazyContext = new InternalContext()

src/decode-logs.ts

@@ -4,13 +4,13 @@ import { btoi } from './impl/pure'
 import { asNumber } from './util'
 
 export type LogDecoding = 'i' | 's' | 'b'
-
 export type DecodedLog<T extends LogDecoding> = T extends 'i' ? bigint : T extends 's' ? string : Uint8Array
 export type DecodedLogs<T extends [...LogDecoding[]]> = {
   [Index in keyof T]: DecodedLog<T[Index]>
 } & { length: T['length'] }
 
 const ABI_RETURN_VALUE_LOG_PREFIX_LENGTH = asNumber(ABI_RETURN_VALUE_LOG_PREFIX.length)
+/** @internal */
 export function decodeLogs<const T extends [...LogDecoding[]]>(logs: bytes[], decoding: T): DecodedLogs<T> {
   return logs.map((log, i) => {
     const value = log.slice(0, ABI_RETURN_VALUE_LOG_PREFIX_LENGTH).equals(ABI_RETURN_VALUE_LOG_PREFIX)

src/impl/acct-params.ts

@@ -5,6 +5,7 @@ import { getApp } from './app-params'
 import { Global } from './global'
 import type { StubUint64Compat } from './primitives'
 
+/** @internal */
 export const getAccount = (acct: Account | StubUint64Compat): Account => {
   const acctId = asMaybeUint64Cls(acct)
   if (acctId !== undefined) {
@@ -14,16 +15,19 @@ export const getAccount = (acct: Account | StubUint64Compat): Account => {
   return acct as Account
 }
 
+/** @internal */
 export const balance = (a: Account | StubUint64Compat): uint64 => {
   const acct = getAccount(a)
   return acct.balance
 }
 
+/** @internal */
 export const minBalance = (a: Account | StubUint64Compat): uint64 => {
   const acct = getAccount(a)
   return acct.minBalance
 }
 
+/** @internal */
 export const appOptedIn = (a: Account | StubUint64Compat, b: Application | StubUint64Compat): boolean => {
   const account = getAccount(a)
   const app = getApp(b)
@@ -34,6 +38,7 @@ export const appOptedIn = (a: Account | StubUint64Compat, b: Application | StubU
   return account.isOptedIn(app)
 }
 
+/** @internal */
 export const AcctParams: typeof op.AcctParams = {
   acctBalance(a: Account | StubUint64Compat): readonly [uint64, boolean] {
     const acct = getAccount(a)

src/impl/app-global.ts

@@ -1,13 +1,14 @@
-import type { Application, bytes, op, uint64 } from '@algorandfoundation/algorand-typescript'
+import type { Application, bytes, BytesCompat, op, uint64, Uint64Compat } from '@algorandfoundation/algorand-typescript'
 import { lazyContext } from '../context-helpers/internal-context'
 import { asBytes } from '../util'
 import { getApp } from './app-params'
 import { toBytes } from './encoded-types'
 import { Bytes, Uint64, type StubBytesCompat, type StubUint64Compat } from './primitives'
 
+/** @internal */
 export const AppGlobal: typeof op.AppGlobal = {
   delete(a: StubBytesCompat): void {
-    lazyContext.ledger.setGlobalState(lazyContext.activeApplication, a, undefined)
+    lazyContext.ledger.setGlobalState(lazyContext.activeApplication, asBytes(a), undefined)
   },
   getBytes(a: StubBytesCompat): bytes {
     return this.getExBytes(0, asBytes(a))[0]
@@ -20,7 +21,7 @@ export const AppGlobal: typeof op.AppGlobal = {
     if (app === undefined) {
       return [Bytes(), false]
     }
-    const [state, exists] = lazyContext.ledger.getGlobalState(app, b)
+    const [state, exists] = lazyContext.ledger.getGlobalState(app, asBytes(b))
     if (!exists) {
       return [Bytes(), false]
     }
@@ -31,13 +32,13 @@ export const AppGlobal: typeof op.AppGlobal = {
     if (app === undefined) {
       return [Uint64(0), false]
     }
-    const [state, exists] = lazyContext.ledger.getGlobalState(app, b)
+    const [state, exists] = lazyContext.ledger.getGlobalState(app, asBytes(b))
     if (!exists) {
       return [Uint64(0), false]
     }
     return [state!.value as uint64, exists]
   },
   put(a: StubBytesCompat, b: StubUint64Compat | StubBytesCompat): void {
-    lazyContext.ledger.setGlobalState(lazyContext.activeApplication, a, b)
+    lazyContext.ledger.setGlobalState(lazyContext.activeApplication, asBytes(a), b as unknown as Uint64Compat | BytesCompat)
   },
 }