Endo API documentation - v0.2.0 / Exports / @endo/captp

Module: @endo/captp

Interfaces

Type Aliases

Variables

Functions

Type Aliases

Checker

Ƭ Checker: (cond: boolean, details?: ses) => boolean

Internal to a useful pattern for writing checking logic (a "checkFoo" function) that can be used to implement a predicate (an "isFoo" function) or a validator (an "assertFoo" function).

A predicate ideally only returns true or false and rarely throws.
A validator throws an informative diagnostic when the predicate would have returned false, and simply returns undefined normally when the predicate would have returned true.
The internal checking function that they share is parameterized by a Checker that determines how to proceed with a failure condition. Predicates pass in an identity function as checker. Validators pass in assertChecker which is a trivial wrapper around assert.

See the various uses for good examples.

Type declaration

▸ (cond, details?): boolean

Parameters

Name	Type
`cond`	`boolean`
`details?`	`ses`

Returns

boolean

Defined in

packages/pass-style/src/types.js:143

ConvertSlotToVal

Ƭ ConvertSlotToVal<Slot>: (slot: Slot, iface?: string) => @endo/pass-style

Type parameters

Name
`Slot`

Type declaration

▸ (slot, iface?): @endo/pass-style

Parameters

Name	Type
`slot`	`Slot`
`iface?`	`string`

Returns

@endo/pass-style

Defined in

packages/marshal/src/types.js:13

ConvertValToSlot

Ƭ ConvertValToSlot<Slot>: (val: @endo/pass-style) => Slot

Type parameters

Name
`Slot`

Type declaration

▸ (val): Slot

Parameters

Name	Type
`val`	`@endo/pass-style`

Returns

Slot

Defined in

packages/marshal/src/types.js:6

CopyArray

Ƭ CopyArray<T>: T[]

A Passable sequence of Passable values.

Type parameters

Name	Type
`T`	extends `Passable` = `Passable`

Defined in

packages/pass-style/src/types.js:91

CopyRecord

Ƭ CopyRecord<T>: Record<string, T>

A Passable dictionary in which each key is a string and each value is Passable.

Type parameters

Name	Type
`T`	extends `Passable` = `Passable`

Defined in

packages/pass-style/src/types.js:98

CopyTagged

Ƭ CopyTagged<Tag, Payload>: Object

A Passable "tagged record" with semantics specific to the tag identified in the [Symbol.toStringTag] property (such as 'copySet', 'copyBag', or 'copyMap'). It must have a property with key equal to the PASS_STYLE export and value 'tagged' and no other properties except [Symbol.toStringTag] and payload.

TODO But TypeScript complains about a declaration like [PASS_STYLE]: 'tagged' because importing packages do not know what PASS_STYLE is, so we appease it with a looser but less accurate definition using symbol index properties and | string.

Type parameters

Name	Type
`Tag`	extends `string` = `string`
`Payload`	extends `Passable` = `Passable`

Index signature

▪ [passStyle: symbol]: "tagged" | string

Type declaration

Name	Type
`[toStringTag]`	`Tag`
`payload`	`Payload`

Defined in

packages/pass-style/src/types.js:110

Encoding

Ƭ Encoding: TreeOf<EncodingElement>

The JSON-representable structure describing the complete shape and pass-by-copy data of a Passable (i.e., everything except the contents of its PassableCap leafs, which are marshalled into referenced Slots).

'@qclass' is a privileged property name in our encoding scheme, so it is disallowed in encoding records and any data that has such a property must instead use the 'hilbert' encoding described above.

Defined in

packages/marshal/src/types.js:68

EncodingClass

Ƭ EncodingClass<T>: Object

Type parameters

Name
`T`

Type declaration

Name	Type
`@qclass`	`T`

Defined in

packages/marshal/src/types.js:21

EncodingElement

Ƭ EncodingElement: boolean | number | null | string | EncodingUnion

Defined in

packages/marshal/src/types.js:59

EncodingUnion

Ƭ EncodingUnion: EncodingClass<"NaN"> | EncodingClass<"undefined"> | EncodingClass<"Infinity"> | EncodingClass<"-Infinity"> | EncodingClass<"bigint"> & { digits: string } | EncodingClass<"@@asyncIterator"> | EncodingClass<"symbol"> & { name: string } | EncodingClass<"error"> & { cause?: Encoding ; errorId?: string ; errors?: Encoding[] ; message: string ; name: string } | EncodingClass<"slot"> & { iface?: string ; index: number } | EncodingClass<"hilbert"> & { original: Encoding ; rest?: Encoding } | EncodingClass<"tagged"> & { payload: Encoding ; tag: string }

Note that the '@@asyncIterator' encoding is deprecated. Use 'symbol' instead.

The 'hilbert' encoding is a reference to the Hilbert Hotel of https://www.ias.edu/ideas/2016/pires-hilbert-hotel . It represents data that has its own '@qclass' property by separately storing the original value of that property and a rest record containing all other properties.

Defined in

packages/marshal/src/types.js:47

FromCapData

Ƭ FromCapData<Slot>: (data: CapData<Slot>) => any

Type parameters

Name
`Slot`

Type declaration

▸ (data): any

Parameters

Name	Type
`data`	`CapData`<`Slot`>

Returns

any

Defined in

packages/marshal/src/types.js:95

FullCompare

Ƭ FullCompare: RankCompare

A FullCompare function satisfies all the invariants stated below for RankCompare's relation with KeyCompare. In addition, its equality is as precise as the KeyCompare comparison defined below, in that, for all Keys x and y, FullCompare(x, y) === 0 iff KeyCompare(x, y) === 0.

For non-keys a FullCompare should be exactly as imprecise as RankCompare. For example, both will treat all errors as in the same equivalence class. Both will treat all promises as in the same equivalence class. Both will order taggeds the same way, which is admittedly weird, as some taggeds will be considered keys and other taggeds will be considered non-keys.

Defined in

packages/marshal/src/types.js:183

HandledExecutor

Ƭ HandledExecutor<R>: @endo/eventual-send

Type parameters

Name	Type
`R`	`unknown`

Defined in

packages/captp/src/captp.js:4

InterfaceSpec

Ƭ InterfaceSpec: string

This is an interface specification. For now, it is just a string, but will eventually be PureData. Either way, it must remain pure, so that it can be safely shared by subgraphs that are not supposed to be able to communicate.

Defined in

packages/pass-style/src/types.js:127

MarshalGetInterfaceOf

Ƭ MarshalGetInterfaceOf: (maybeRemotable: any) => InterfaceSpec | undefined

Simple semantics, just tell what interface (or undefined) a remotable has.

Type declaration

▸ (maybeRemotable): InterfaceSpec | undefined

Parameters

Name	Type	Description
`maybeRemotable`	`any`	the value to check

Returns

InterfaceSpec | undefined

Defined in

packages/pass-style/src/types.js:135

PassStyle

Defined in

packages/pass-style/src/types.js:14

PassStyleOf

Ƭ PassStyleOf: (passable: Passable) => PassStyle

Type declaration

▸ (passable): PassStyle

Parameters

Name	Type
`passable`	`Passable`

Returns

PassStyle

Defined in

packages/pass-style/src/types.js:46

Passable

Ƭ Passable: any

A Passable is acyclic data that can be marshalled. It must be hardened to remain stable (even if some components are proxies; see PureData restriction below), and is classified by PassStyle:

Atomic primitive values have a PrimitiveStyle (PassStyle 'undefined' | 'null' | 'boolean' | 'number' | 'bigint' | 'string' | 'symbol').
Containers aggregate other Passables into
- sequences as CopyArrays (PassStyle 'copyArray'), or
- string-keyed dictionaries as CopyRecords (PassStyle 'copyRecord'), or
- higher-level types as CopyTaggeds (PassStyle 'tagged').
PassableCaps (PassStyle 'remotable' | 'promise') expose local values to remote interaction.
As a special case to support system observability, error objects are Passable (PassStyle 'error').

A Passable is essentially a pass-by-copy superstructure with a pass-by-reference exit point at the site of each PassableCap (which marshalling represents using 'slots').

Defined in

packages/pass-style/src/types.js:21

PassableCap

Ƭ PassableCap: Promise | RemotableObject

The authority-bearing leaves of a Passable's pass-by-copy superstructure.

Defined in

packages/pass-style/src/types.js:84

PrimitiveStyle

Defined in

packages/pass-style/src/types.js:6

PureData

Ƭ PureData: Passable

A Passable is PureData when its entire data structure is free of PassableCaps (remotables and promises) and error objects. PureData is an arbitrary composition of primitive values into CopyArray and/or CopyRecord and/or CopyTagged containers (or a single primitive value with no container), and is fully pass-by-copy.

This restriction assures absence of side effects and interleaving risks given that none of the containers can be a Proxy instance. TODO SECURITY BUG we plan to enforce this, giving PureData the same security properties as the proposed Records and Tuples.

Given this (currently counter-factual) assumption, a PureData value cannot be used as a communications channel, and can therefore be safely shared with subgraphs that should not be able to communicate with each other. Without that assumption, such a guarantee requires a marshal-unmarshal round trip (as exists between vats) to produce data structures disconnected from any potential proxies.

Defined in

packages/pass-style/src/types.js:52

RankCompare

Ƭ RankCompare: (left: any, right: any) => RankComparison

Returns -1, 0, or 1 depending on whether the rank of left is respectively before, tied-with, or after the rank of right.

This comparison function is valid as argument to Array.prototype.sort. This is sometimes described as a "total order" but, depending on your definitions, this is technically incorrect because it may return 0 to indicate that two distinguishable elements such as -0 and 0 are tied (i.e., are in the same equivalence class for the purposes of this ordering). If each such equivalence class is a rank and ranks are disjoint, then this "rank order" is a true total order over these ranks. In mathematics this goes by several other names such as "total preorder".

This function establishes a total rank order over all passables. To do so it makes arbitrary choices, such as that all strings are after all numbers. Thus, this order is not intended to be used directly as a comparison with useful semantics. However, it must be closely enough related to such comparisons to aid in implementing lookups based on those comparisons. For example, in order to get a total order among ranks, we put NaN after all other JavaScript "number" values (i.e., IEEE 754 floating-point values). But otherwise, we rank JavaScript numbers by signed magnitude, with 0 and -0 tied. A semantically useful ordering would also compare magnitudes, and so agree with the rank ordering of all values other than NaN. An array sorted by rank would enable range queries by magnitude.

Type declaration

▸ (left, right): RankComparison

Parameters

Name	Type	Description
`left`	`any`	a Passable
`right`	`any`	a Passable

Returns

RankComparison

Defined in

packages/marshal/src/types.js:151

RankComparison

Ƭ RankComparison: -1 | 0 | 1

The result of a RankCompare function that defines a rank-order, i.e., a total preorder in which different elements are always comparable but can be tied for the same rank. See RankCompare.

Defined in

packages/marshal/src/types.js:144

RankCover

Ƭ RankCover: [string, string]

RankCover represents the inclusive lower bound and inclusive upper bound of a string-comparison range that covers all possible encodings for a set of values.

Defined in

packages/marshal/src/types.js:137

RemotableObject

Ƭ RemotableObject: Passable

An object marked as remotely accessible using the Far or Remotable functions, or a local presence representing such a remote object.

Defined in

packages/pass-style/src/types.js:77

RemoteKit

Ƭ RemoteKit<R>: @endo/eventual-send

Type parameters

Name	Type
`R`	`unknown`

Defined in

packages/captp/src/captp.js:5

Settler

Ƭ Settler<R>: @endo/eventual-send

Type parameters

Name	Type
`R`	`unknown`

Defined in

packages/captp/src/captp.js:3

ToCapData

Ƭ ToCapData<Slot>: (val: any) => CapData<Slot>

Type parameters

Name
`Slot`

Type declaration

▸ (val): CapData<Slot>

Parameters

Name	Type	Description
`val`	`any`	a Passable

Returns

CapData<Slot>

Defined in

packages/marshal/src/types.js:88

TreeOf

Ƭ TreeOf<T>: T | { [x: PropertyKey]: TreeOf<T>; }

Type parameters

Name
`T`

Defined in

packages/marshal/src/types.js:64

Variables

GET_METHOD_NAMES

• Const GET_METHOD_NAMES: "__getMethodNames__"

The name of the automatically added default meta-method for obtaining a list of all methods of an object declared with Far, or an object that inherits from an object declared with Far.

Modeled on GET_INTERFACE_GUARD from @endo/exo.

TODO Name to be bikeshed. Perhaps even whether it is a string or symbol to be bikeshed. See https://github.com/endojs/endo/pull/1809#discussion_r1388052454

HAZARD: Beware that an exo's interface can change across an upgrade, so remotes that cache it can become stale.

Defined in

packages/pass-style/src/make-far.js:145

MIN_DATA_BUFFER_LENGTH

• Const MIN_DATA_BUFFER_LENGTH: 1

Defined in

packages/captp/src/atomics.js:6

MIN_TRANSFER_BUFFER_LENGTH

• Const MIN_TRANSFER_BUFFER_LENGTH: number

Defined in

packages/captp/src/atomics.js:11

PASS_STYLE

• Const PASS_STYLE: typeof PASS_STYLE

Defined in

packages/pass-style/src/passStyle-helpers.js:48

QCLASS

• Const QCLASS: "@qclass"

Special property name that indicates an encoding that needs special decoding.

Defined in

packages/marshal/src/encodeToCapData.js:42

TRANSFER_OVERHEAD_LENGTH

• Const TRANSFER_OVERHEAD_LENGTH: number

Defined in

packages/captp/src/atomics.js:9

Functions

E

▸ E<T>(x): ECallableOrMethods<RemoteFunctions<T>>

E(x) returns a proxy on which you can call arbitrary methods. Each of these method calls returns a promise. The method will be invoked on whatever 'x' designates (or resolves to) in a future turn, not this one.

Type parameters

Name
`T`

Parameters

Name	Type	Description
`x`	`T`	target for method/function call

Returns

ECallableOrMethods<RemoteFunctions<T>>

method/function call proxy

Defined in

packages/eventual-send/src/no-shim.js:4

Far

▸ Far<T>(farName, remotable?): T & RemotableBrand<{}, T>

Mark an object to be exposed for remote interaction and give it a suggestive interface name for debugging.

All properties of the object have to be methods, not data.

The object must not be hardened before it is marked. It will be hardened after marking.

For far objects (as opposed to far functions), also adds __getMethodNames__ method that returns an array of all the method names, if there is not yet any method named __getMethodNames__.

Type parameters

Name	Type
`T`	extends `Object`

Parameters

Name	Type	Default value	Description
`farName`	`string`	`undefined`	This name will be prepended with `Alleged:` for now to form the `Remotable` `iface` argument.
`remotable?`	`T`	`undefined`	The object to be marked as remotable

Returns

T & RemotableBrand<{}, T>

Example

Far('Employee', { getManager })

Defined in

packages/pass-style/src/make-far.js:186

Nat

▸ Nat(allegedNum): bigint

If allegedNumber passes the isNat test, then return it as a bigint. Otherwise throw an appropriate error.

If allegedNum is neither a bigint nor a number, Nat throws a TypeError. Otherwise, if it is not a safely representable non-negative integer, Nat throws a RangeError. Otherwise, it is converted to a bigint if necessary and returned.

Parameters

Name	Type
`allegedNum`	`unknown`

Returns

bigint

Defined in

packages/nat/src/index.js:56

Remotable

▸ Remotable<T>(iface?, props?, remotable?): T & RemotableBrand<{}, T>

Create and register a Remotable. After this, getInterfaceOf(remotable) returns iface.

// https://github.com/Agoric/agoric-sdk/issues/804

Type parameters

Name	Type
`T`	extends `Object`

Parameters

Name	Type	Default value	Description
`iface?`	`string`	`'Remotable'`	The interface specification for the remotable. For now, a string iface must be "Remotable" or begin with "Alleged: " or "DebugName: ", to serve as the alleged name. More general ifaces are not yet implemented. This is temporary. We include the "Alleged" or "DebugName" as a reminder that we do not yet have SwingSet or Comms Vat support for ensuring this is according to the vat hosting the object. Currently, Alice can tell Bob about Carol, where VatA (on Alice's behalf) misrepresents Carol's `iface`. VatB and therefore Bob will then see Carol's `iface` as misrepresented by VatA.
`props?`	`undefined`	`undefined`	Currently may only be undefined. That plan is that own-properties are copied to the remotable
`remotable?`	`T`	`undefined`	The object used as the remotable

Returns

T & RemotableBrand<{}, T>

remotable, modified for debuggability

Defined in

packages/pass-style/src/make-far.js:79

ToFarFunction

▸ ToFarFunction(farName, func): (...args: any[]) => any

Coerce func to a far function that preserves its call behavior. If it is already a far function, return it. Otherwise make and return a new far function that wraps func and forwards calls to it. This works even if func is already frozen. ToFarFunction is to be used when the function comes from elsewhere under less control. For functions you author in place, better to use Far on their function literal directly.

Parameters

Name	Type	Description
`farName`	`string`	to be used only if `func` is not already a far function.
`func`	(...`args`: `any`[]) => `any`	-

Returns

fn

▸ (...args): any

Parameters

Name	Type
`...args`	`any`[]

Returns

any

Defined in

packages/pass-style/src/make-far.js:214

assertChecker

▸ assertChecker(cond, details?): boolean

Below we have a series of predicate functions and their (curried) assertion functions. The semantics of the assertion function is just to assert that the corresponding predicate function would have returned true. But it reproduces the internal tests so failures can give a better error message.

Parameters

Name	Type
`cond`	`boolean`
`details?`	`Details`

Returns

boolean

Defined in

packages/pass-style/src/passStyle-helpers.js:75

assertCopyArray

▸ assertCopyArray(array, optNameOfArray): asserts array is CopyArray<any>

Parameters

Name	Type
`array`	`any`
`optNameOfArray`	`undefined` \| `string`

Returns

asserts array is CopyArray<any>

Defined in

packages/pass-style/src/typeGuards.js:52

assertPassable

▸ assertPassable(val): void

Parameters

Name	Type
`val`	`any`

Returns

void

Defined in

packages/pass-style/src/passStyleOf.js:234

assertPassableError

▸ assertPassableError(err): asserts err is Error

Parameters

Name	Type
`err`	`unknown`

Returns

asserts err is Error

Defined in

packages/pass-style/src/passStyleOf.js:300

assertPassableString

▸ assertPassableString(str): asserts str is string

For now, if ONLY_WELL_FORMED_STRINGS_PASSABLE environment option is 'enabled', then assertPassableString is the same as assertWellFormedString. Otherwise assertPassableString just asserts that str is a string.

Currently, ONLY_WELL_FORMED_STRINGS_PASSABLE defaults to 'disabled' because we do not yet know the performance impact. Later, if we decide we can afford it, we'll first change the default to 'enabled' and ultimately remove the switch altogether. Be prepared for these changes.

TODO once the switch is removed, simplify assertPassableString to simply be assertWellFormedString.

TODO update https://github.com/Agoric/agoric-sdk/blob/master/docs/env.md which is unfortunately in the wrong repo to be updated in the same change.

Parameters

Name	Type
`str`	`unknown`

Returns

asserts str is string

Defined in

packages/pass-style/src/string.js:84

assertPassableSymbol

▸ assertPassableSymbol(sym): true

Parameters

Name	Type
`sym`	`any`

Returns

true

Defined in

packages/pass-style/src/symbol.js:38

assertRankSorted

▸ assertRankSorted(sorted, compare): true

Parameters

Name	Type
`sorted`	`any`[]
`compare`	`RankCompare`

Returns

true

Defined in

packages/marshal/src/rankOrder.js:272

assertRecord

▸ assertRecord(record, optNameOfRecord): asserts record is CopyRecord<any>

Parameters

Name	Type
`record`	`any`
`optNameOfRecord`	`undefined` \| `string`

Returns

asserts record is CopyRecord<any>

Defined in

packages/pass-style/src/typeGuards.js:69

assertRemotable

▸ assertRemotable(remotable, optNameOfRemotable): asserts remotable is any

Parameters

Name	Type
`remotable`	`any`
`optNameOfRemotable`	`undefined` \| `string`

Returns

asserts remotable is any

Defined in

packages/pass-style/src/typeGuards.js:86

assertWellFormedString

▸ assertWellFormedString(str): asserts str is string

Returns normally when isWellFormedString(str) would return true. Throws a diagnostic error when isWellFormedString(str) would return false.

Parameters

Name	Type
`str`	`unknown`

Returns

asserts str is string

Defined in

packages/pass-style/src/string.js:54

compareAntiRank

▸ compareAntiRank(left, right): RankComparison

Parameters

Name	Type	Description
`left`	`any`	a Passable
`right`	`any`	a Passable

Returns

RankComparison

Defined in

packages/marshal/src/rankOrder.js:437

compareRank

▸ compareRank(left, right): RankComparison

Parameters

Name	Type	Description
`left`	`any`	a Passable
`right`	`any`	a Passable

Returns

RankComparison

Defined in

packages/marshal/src/rankOrder.js:437

decodeToJustin

▸ decodeToJustin(encoding, shouldIndent?, slots?): string

Parameters

Name	Type	Default value
`encoding`	`Encoding`	`undefined`
`shouldIndent`	`undefined` \| `boolean`	`false`
`slots?`	`any`[]	`[]`

Returns

string

Defined in

packages/marshal/src/marshal-justin.js:128

deeplyFulfilled

▸ deeplyFulfilled(val): Promise<any>

Given a Passable val whose pass-by-copy structure may contain leaf promises, return a promise for a replacement Passable, where that replacement is deeply fulfilled, i.e., its pass-by-copy structure does not contain any promises.

This is a deep form of Promise.all specialized for Passables. For each encountered promise, replace it with the deeply fulfilled form of its fulfillment. If any of the promises reject, then the promise for the replacement rejects. If any of the promises never settle, then the promise for the replacement never settles.

If the replacement would not be Passable, i.e., if val is not Passable, or if any of the transitive promises fulfill to something that is not Passable, then the returned promise rejects.

If val or its parts are non-key Passables only because they contains promises, the deeply fulfilled forms of val or its parts may be keys. This is for the higher "store" level of abstraction to determine, because it defines the "key" notion in question.

// TODO: That higher level is in the process of being migrated from // @agoric/store to @endo/patterns. Once that is far enough along, // revise the above comment to match. // See https://github.com/endojs/endo/pull/1451

Parameters

Name	Type
`val`	`any`

Returns

Promise<any>

Defined in

packages/marshal/src/deeplyFulfilled.js:45

filterIterable

▸ filterIterable<T>(baseIterable, pred): Iterable<T>

The result iterator has a subset of the non-final values from the baseIterator --- those for which pred(value) was truthy. The result has the same termination as the baseIterator -- the same completion value or failure reason.

Type parameters

Name
`T`

Parameters

Name	Type
`baseIterable`	`Iterable`<`T`>
`pred`	(`value`: `T`) => `boolean`

Returns

Iterable<T>

Defined in

packages/pass-style/src/iter-helpers.js:41

getErrorConstructor

▸ getErrorConstructor(name): undefined | GenericErrorConstructor

Because the error constructor returned by this function might be AggregateError, which has different construction parameters from the other error constructors, do not use it directly to try to make an error instance. Rather, use makeError which encapsulates this non-uniformity.

Parameters

Name	Type
`name`	`string`

Returns

undefined | GenericErrorConstructor

Defined in

packages/pass-style/src/error.js:48

getInterfaceOf

▸ getInterfaceOf(maybeRemotable): undefined | string

Parameters

Name	Type	Description
`maybeRemotable`	`any`	the value to check

Returns

undefined | string

Defined in

packages/pass-style/src/remotable.js:166

getPassStyleCover

▸ getPassStyleCover(passStyle): RankCover

Associate with each passStyle a RankCover that may be an overestimate, and whose results therefore need to be filtered down. For example, because there is not a smallest or biggest bigint, bound it by NaN (the last place number) and '' (the empty string, which is the first place string). Thus, a range query using this range may include these values, which would then need to be filtered out.

Parameters

Name	Type
`passStyle`	`PassStyle`

Returns

RankCover

Defined in

packages/marshal/src/rankOrder.js:92

getTag

▸ getTag(tagRecord): any

Parameters

Name	Type
`tagRecord`	`any`

Returns

any

Defined in

packages/pass-style/src/passStyle-helpers.js:122

hasOwnPropertyOf

▸ hasOwnPropertyOf(obj, prop): any

Parameters

Name	Type
`obj`	`any`
`prop`	`any`

Returns

any

Defined in

packages/pass-style/src/passStyle-helpers.js:29

intersectRankCovers

▸ intersectRankCovers(compare, covers): RankCover

Parameters

Name	Type
`compare`	`RankCompare`
`covers`	`RankCover`[]

Returns

RankCover

Defined in

packages/marshal/src/rankOrder.js:424

isCopyArray

▸ isCopyArray(arr): arr is CopyArray<any>

Check whether the argument is a pass-by-copy array, AKA a "copyArray" in @endo/marshal terms

Parameters

Name	Type
`arr`	`any`

Returns

arr is CopyArray<any>

Defined in

packages/pass-style/src/typeGuards.js:22

isEncodedRemotable

▸ isEncodedRemotable(encoded): boolean

Parameters

Name	Type
`encoded`	`any`

Returns

boolean

Defined in

packages/marshal/src/encodePassable.js:848

isErrorLike

▸ isErrorLike(candidate): boolean

Validating error objects are passable raises a tension between security vs preserving diagnostic information. For errors, we need to remember the error itself exists to help us diagnose a bug that's likely more pressing than a validity bug in the error itself. Thus, whenever it is safe to do so, we prefer to let the error-like test succeed and to couch these complaints as notes on the error.

To resolve this, such a malformed error object will still pass isErrorLike so marshal can use this for top level error to report from, even if it would not actually validate. Instead, the diagnostics that assertError would have reported are attached as notes to the malformed error. Thus, a malformed error is passable by itself, but not as part of a passable structure.

Parameters

Name	Type
`candidate`	`unknown`

Returns

boolean

Defined in

packages/pass-style/src/error.js:85

isObject

▸ isObject(val): boolean

Parameters

Name	Type
`val`	`any`

Returns

boolean

Defined in

packages/pass-style/src/passStyle-helpers.js:33

isPassable

▸ isPassable(specimen): specimen is any

Is specimen Passable? This returns true iff passStyleOf(specimen) returns a string. This returns false iff passStyleOf(specimen) throws. Under no normal circumstance should isPassable(specimen) throw.

TODO Deprecate and ultimately delete @agoric/base-zone's `isPassable' in favor of this one. See https://github.com/endojs/endo/issues/2096

TODO implement an isPassable that does not rely on try/catch. This implementation is just a standin until then. See https://github.com/endojs/endo/issues/2096

Parameters

Name	Type
`specimen`	`any`

Returns

specimen is any

Defined in

packages/pass-style/src/passStyleOf.js:255

isPassableError

▸ isPassableError(err): err is Error

Parameters

Name	Type
`err`	`unknown`

Returns

err is Error

Defined in

packages/pass-style/src/passStyleOf.js:293

isPassableSymbol

▸ isPassableSymbol(sym): boolean

The passable symbols are the well known symbols (the symbol values of static properties of the Symbol constructor) and the registered symbols.

Parameters

Name	Type
`sym`	`any`

Returns

boolean

Defined in

packages/pass-style/src/symbol.js:33

isRankSorted

▸ isRankSorted(passables, compare): boolean

Parameters

Name	Type
`passables`	`any`[]
`compare`	`RankCompare`

Returns

boolean

Defined in

packages/marshal/src/rankOrder.js:251

isRecord

▸ isRecord(record): record is CopyRecord<any>

Check whether the argument is a pass-by-copy record, AKA a "copyRecord" in @endo/marshal terms

Parameters

Name	Type
`record`	`any`

Returns

record is CopyRecord<any>

Defined in

packages/pass-style/src/typeGuards.js:32

isRemotable

▸ isRemotable(remotable): remotable is any

Check whether the argument is a remotable.

Parameters

Name	Type
`remotable`	`any`

Returns

remotable is any

Defined in

packages/pass-style/src/typeGuards.js:41

isWellFormedString

▸ isWellFormedString(str): any

Is the argument a well-formed string?

Unfortunately, the standard built-in String.prototype.isWellFormed does a ToString on its input, causing it to judge non-strings to be well-formed strings if they coerce to a well-formed strings. This recapitulates the mistake in having the global isNaN coerce its inputs, causing it to judge non-string to be NaN if they coerce to NaN.

This isWellFormedString function only judges well-formed strings to be well-formed strings. For all non-strings it returns false.

Parameters

Name	Type
`str`	`any`

Returns

any

Defined in

packages/pass-style/src/string.js:26

makeAtomicsTrapGuest

▸ makeAtomicsTrapGuest(transferBuffer): TrapGuest

Create a trapGuest that can be paired with makeAtomicsTrapHost.

This guest iterates through the consecutive slices of the JSON-encoded data, then returns it.

Parameters

Name	Type
`transferBuffer`	`SharedArrayBuffer`

Returns

TrapGuest

Defined in

packages/captp/src/atomics.js:109

makeAtomicsTrapHost

▸ makeAtomicsTrapHost(transferBuffer): TrapHost

Create a trapHost that can be paired with makeAtomicsTrapGuest.

This host encodes the transfer buffer and returns it in consecutive slices when the guest iterates over it.

Parameters

Name	Type
`transferBuffer`	`SharedArrayBuffer`

Returns

TrapHost

Defined in

packages/captp/src/atomics.js:54

makeCapTP

▸ makeCapTP(ourId, rawSend, bootstrapObj?, opts?): Object

Create a CapTP connection.

Parameters

Name	Type	Default value	Description
`ourId`	`string`	`undefined`	our name for the current side
`rawSend`	(`obj`: `Record`<`string`, `any`>) => `void`	`undefined`	send a JSONable packet
`bootstrapObj`	`any`	`undefined`	the object to export to the other side
`opts`	`CapTPOptions`	`{}`	options to the connection

Returns

Object

Name	Type
`Trap`	`undefined` \| `Trap`
`abort`	(`reason`: `undefined`) => `void`
`dispatch`	(`obj`: `any`) => `boolean`
`getBootstrap`	() => `Promise`<`any`>
`getStats`	() => { `gc`: { `DROPPED`: `number` = 0 } ; `recv`: {} ; `send`:
`isOnlyLocal`	(`specimen`: `any`) => `boolean`
`makeTrapHandler`	(`name`: `any`, `obj`: `any`) => `any`
`serialize`	`ToCapData`<`string`>
`unserialize`	`FromCapData`<`string`>

Defined in

packages/captp/src/captp.js:72

makeDecodePassable

▸ makeDecodePassable(decodeOptions?): (encoded: string, skip?: number) => any

Parameters

Name	Type
`decodeOptions?`	`DecodeOptions`

Returns

fn

▸ (encoded, skip?): any

Parameters

Name	Type
`encoded`	`string`
`skip?`	`number`

Returns

any

Defined in

packages/marshal/src/encodePassable.js:842

makeEncodePassable

▸ makeEncodePassable(encodeOptions?): (p: any) => string

Parameters

Name	Type
`encodeOptions?`	`EncodeOptions`

Returns

fn

▸ (p): string

Parameters

Name	Type
`p`	`any`

Returns

string

Defined in

packages/marshal/src/encodePassable.js:832

makeFullOrderComparatorKit

▸ makeFullOrderComparatorKit(longLived?): FullComparatorKit

Create a comparator kit in which remotables are fully ordered by the order in which they are first seen by this comparator kit. BEWARE: This is observable mutable state, so such a comparator kit should never be shared among subsystems that should not be able to communicate.

Note that this order does not meet the requirements for store ordering, since it has no memory of deleted keys.

These full order comparator kit is strictly more precise that the rank order comparator kits above. As a result, any array which is sorted by such a full order will pass the isRankSorted test with a corresponding rank order.

An array which is sorted by a fresh full order comparator, i.e., one that has not yet seen any remotables, will of course remain sorted by according to that full order comparator. An array of scalars sorted by a fresh full order will remain sorted even according to a new fresh full order comparator, since it will see the remotables in the same order again. Unfortunately, this is not true of arrays of passables in general.

Parameters

Name	Type	Default value
`longLived`	`undefined` \| `boolean`	`false`

Returns

FullComparatorKit

Defined in

packages/marshal/src/rankOrder.js:466

makeLoopback

▸ makeLoopback(ourId, nearOptions?, farOptions?): Object

Create an async-isolated channel to an object.

Parameters

Name	Type
`ourId`	`string`
`nearOptions?`	`CapTPOptions`
`farOptions?`	`CapTPOptions`

Returns

Object

Name	Type
`Trap`	`undefined` \| `Trap`
`getFarStats`	() => `any`
`getNearStats`	() => `any`
`isOnlyFar`	(`x`: `any`) => `boolean`
`isOnlyNear`	(`x`: `any`) => `boolean`
`makeFar`	<T>(`x`: `T`) => `ERef`<`T`>
`makeNear`	<T>(`x`: `T`) => `ERef`<`T`>
`makeTrapHandler`	<T>(`x`: `T`) => `T`

Defined in

packages/captp/src/loopback.js:30

makeMarshal

▸ makeMarshal<Slot>(convertValToSlot?, convertSlotToVal?, options?): Object

Type parameters

Name
`Slot`

Parameters

Name	Type	Default value
`convertValToSlot?`	`ConvertValToSlot`<`Slot`>	`defaultValToSlotFn`
`convertSlotToVal?`	`ConvertSlotToVal`<`Slot`>	`defaultSlotToValFn`
`options`	`MakeMarshalOptions`	`{}`

Returns

Object

Name	Type	Description
`fromCapData`	`FromCapData`<`Slot`>	-
`serialize`	`ToCapData`<`Slot`>	`Deprecated` use toCapData
`toCapData`	`ToCapData`<`Slot`>	-
`unserialize`	`FromCapData`<`Slot`>	`Deprecated` use fromCapData

Defined in

packages/marshal/src/marshal.js:49

makePassableKit

▸ makePassableKit(options?): PassableKit

Parameters

Name	Type
`options?`	`EncodeOptions` & `DecodeOptions`

Returns

PassableKit

Defined in

packages/marshal/src/encodePassable.js:749

makeTagged

▸ makeTagged(tag, payload): any

Parameters

Name	Type
`tag`	`any`
`payload`	`any`

Returns

any

Defined in

packages/pass-style/src/makeTagged.js:9

mapIterable

▸ mapIterable<T, U>(baseIterable, func): Iterable<U>

The result iterator has as many elements as the baseIterator and have the same termination -- the same completion value or failure reason. But the non-final values are the corresponding non-final values from baseIterator as transformed by func.

Type parameters

Name
`T`
`U`

Parameters

Name	Type
`baseIterable`	`Iterable`<`T`>
`func`	(`value`: `T`) => `U`

Returns

Iterable<U>

Defined in

packages/pass-style/src/iter-helpers.js:14

nameForPassableSymbol

▸ nameForPassableSymbol(sym): undefined | string

If sym is a passable symbol, return a string that uniquely identifies this symbol. If sym is a non-passable symbol, return undefined.

The passable symbols are the well known symbols (the symbol values of static properties of the Symbol constructor) and the registered symbols. Since the registration string of a registered symbol can be any string, if we simply used that to identify those symbols, there would not be any remaining strings left over to identify the well-known symbols. Instead, we reserve strings beginning with "@@" for purposes of this encoding. We identify a well known symbol such as Symbol.iterator by prefixing the property name with "@@", such as "@@iterator". For registered symbols whose name happens to begin with "@@", such as Symbol.for('@@iterator') or Symbol.for('@@foo'), we identify them by prefixing them with an extra "@@", such as "@@@@iterator" or "@@@@foo". (This is the Hilbert Hotel encoding technique.)

Parameters

Name	Type
`sym`	`symbol`

Returns

undefined | string

Defined in

packages/pass-style/src/symbol.js:64

parse

▸ parse(str): any

Parameters

Name	Type
`str`	`string`

Returns

any

Defined in

packages/marshal/src/marshal-stringify.js:49

passStyleOf

▸ passStyleOf(passable): PassStyle

If there is already a PassStyleOfEndowmentSymbol property on the global, then presumably it was endowed for us by liveslots with a passStyleOf function, so we should use and export that one instead. Other software may have left it for us here, but it would require write access to our global, or the ability to provide endowments to our global, both of which seems adequate as a test of whether it is authorized to serve the same role as liveslots.

NOTE HAZARD: This use by liveslots does rely on passStyleOf being deterministic. If it is not, then in a liveslot-like virtualized environment, it can be used to detect GC.

Parameters

Name	Type
`passable`	`any`

Returns

PassStyle

Defined in

packages/pass-style/src/passStyleOf.js:224

passableSymbolForName

▸ passableSymbolForName(name): undefined | symbol

If name is a string that could have been produced by nameForPassableSymbol, return the symbol argument it was produced to represent.

If name does not begin with "@@", then just the corresponding registered symbol, Symbol.for(name). If name is "@@" followed by a well known symbol's property name on Symbol such "@@iterator", return that well known symbol such as Symbol.iterator Ifnamebegins with"@@@@"it encodes the registered symbol whose name begins with"@@"instead. Otherwise, if name begins with"@@"` it may encode a registered symbol from a future version of JavaScript, but it is not one we can decode yet, so throw.

Parameters

Name	Type
`name`	`string`

Returns

undefined | symbol

Defined in

packages/pass-style/src/symbol.js:98

recordNames

▸ recordNames<T>(record): string[]

Assuming that record is a CopyRecord, we have only string-named own properties. recordNames returns those name reverse sorted, because that's how records are compared, encoded, and sorted.

Type parameters

Name
`T`

Parameters

Name	Type
`record`	`CopyRecord`<`T`>

Returns

string[]

Defined in

packages/marshal/src/encodePassable.js:50

recordValues

▸ recordValues<T>(record, names): T[]

Assuming that record is a CopyRecord and names is recordNames(record), return the corresponding array of property values.

Type parameters

Name
`T`

Parameters

Name	Type
`record`	`CopyRecord`<`T`>
`names`	`string`[]

Returns

T[]

Defined in

packages/marshal/src/encodePassable.js:68

sortByRank

▸ sortByRank(passables, compare): any[]

TODO SECURITY BUG: https://github.com/Agoric/agoric-sdk/issues/4260 sortByRank currently uses Array.prototype.sort directly, and so only works correctly when given a compare function that considers undefined strictly bigger (>) than everything else. This is because Array.prototype.sort bizarrely moves all undefineds to the end of the array regardless, without consulting the compare function. This is a genuine bug for us NOW because sometimes we sort in reverse order by passing a reversed rank comparison function.

Parameters

Name	Type
`passables`	`Iterable`<`any`>
`compare`	`RankCompare`

Returns

any[]

Defined in

packages/marshal/src/rankOrder.js:293

stringify

▸ stringify(val): string

Parameters

Name	Type
`val`	`any`

Returns

string

Defined in

packages/marshal/src/marshal-stringify.js:42

toPassableError

▸ toPassableError(err): Error

Return a new passable error that propagates the diagnostic info of the original, and is linked to the original as a note.

Parameters

Name	Type
`err`	`Error`

Returns

Error

Defined in

packages/pass-style/src/passStyleOf.js:311

trivialComparator

▸ trivialComparator(left, right): -1 | 0 | 1

Parameters

Name	Type
`left`	`any`
`right`	`any`

Returns

-1 | 0 | 1

Defined in

packages/marshal/src/rankOrder.js:49

unionRankCovers

▸ unionRankCovers(compare, covers): RankCover

Parameters

Name	Type
`compare`	`RankCompare`
`covers`	`RankCover`[]

Returns

RankCover

Defined in

packages/marshal/src/rankOrder.js:405

zeroPad

▸ zeroPad(n, size): string

Parameters

Name	Type
`n`	`unknown`
`size`	`number`

Returns

string

Defined in

packages/marshal/src/encodePassable.js:81

Module: @endo/captp ​

Table of contents ​

Interfaces ​

Type Aliases ​

Variables ​

Functions ​

Type Aliases ​

Checker ​

Type declaration ​

Parameters ​

Returns ​

Defined in ​

ConvertSlotToVal ​

Type parameters ​

Type declaration ​

Parameters ​

Returns ​

Defined in ​

ConvertValToSlot ​

Type parameters ​

Type declaration ​

Parameters ​

Returns ​

Defined in ​

CopyArray ​

Type parameters ​

Defined in ​

CopyRecord ​

Type parameters ​

Defined in ​

CopyTagged ​

Type parameters ​

Index signature ​

Type declaration ​

Defined in ​

Encoding ​

Defined in ​

EncodingClass ​

Type parameters ​

Type declaration ​

Defined in ​

EncodingElement ​

Defined in ​

EncodingUnion ​

Defined in ​

FromCapData ​

Type parameters ​

Type declaration ​

Parameters ​

Returns ​

Defined in ​

FullCompare ​

Defined in ​

HandledExecutor ​

Type parameters ​

Defined in ​

InterfaceSpec ​

Defined in ​

MarshalGetInterfaceOf ​

Type declaration ​

Parameters ​

Returns ​

Defined in ​

PassStyle ​

Defined in ​

PassStyleOf ​

Type declaration ​

Parameters ​

Returns ​

Defined in ​

Passable ​

Defined in ​

PassableCap ​

Defined in ​

PrimitiveStyle ​

Defined in ​

PureData ​

Defined in ​

RankCompare ​

Type declaration ​

Module: @endo/captp

Table of contents

Interfaces

Type Aliases

Variables

Functions

Type Aliases

Checker

Type declaration

Parameters

Returns

Defined in

ConvertSlotToVal

Type parameters

Type declaration

Parameters

Returns

Defined in

ConvertValToSlot

Type parameters

Type declaration

Parameters

Returns

Defined in

CopyArray

Type parameters

Defined in

CopyRecord

Type parameters

Defined in

CopyTagged

Type parameters

Index signature

Type declaration

Defined in

Encoding

Defined in

EncodingClass

Type parameters

Type declaration

Defined in

EncodingElement

Defined in

EncodingUnion

Defined in

FromCapData

Type parameters

Type declaration

Parameters

Returns

Defined in

FullCompare

Defined in

HandledExecutor

Type parameters

Defined in

InterfaceSpec

Defined in

MarshalGetInterfaceOf

Type declaration

Parameters

Returns

Defined in

PassStyle

Defined in

PassStyleOf

Type declaration

Parameters

Returns

Defined in

Passable

Defined in

PassableCap

Defined in

PrimitiveStyle

Defined in

PureData

Defined in

RankCompare

Type declaration