Endo API documentation - v0.2.0 / Exports / @endo/pass-style
Module: @endo/pass-style
Table of contents
Type Aliases
- Checker
- CopyArray
- CopyRecord
- CopyTagged
- InterfaceSpec
- MarshalGetInterfaceOf
- PassStyle
- PassStyleOf
- Passable
- PassableCap
- PrimitiveStyle
- PureData
- RemotableObject
Variables
Functions
- Far
- Remotable
- ToFarFunction
- assertChecker
- assertCopyArray
- assertPassable
- assertPassableError
- assertPassableString
- assertPassableSymbol
- assertRecord
- assertRemotable
- assertWellFormedString
- filterIterable
- getErrorConstructor
- getInterfaceOf
- getTag
- hasOwnPropertyOf
- isCopyArray
- isErrorLike
- isObject
- isPassable
- isPassableError
- isPassableSymbol
- isRecord
- isRemotable
- isWellFormedString
- makeTagged
- mapIterable
- nameForPassableSymbol
- passStyleOf
- passableSymbolForName
- toPassableError
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
trueorfalseand rarely throws. - A validator throws an informative diagnostic when the predicate would have returned
false, and simply returnsundefinednormally when the predicate would have returnedtrue. - The internal checking function that they share is parameterized by a
Checkerthat determines how to proceed with a failure condition. Predicates pass in an identity function as checker. Validators pass inassertCheckerwhich is a trivial wrapper aroundassert.
See the various uses for good examples.
Type declaration
▸ (cond, details?): boolean
Parameters
| Name | Type |
|---|---|
cond | boolean |
details? | ses |
Returns
boolean
Defined in
CopyArray
Ƭ CopyArray<T>: T[]
A Passable sequence of Passable values.
Type parameters
| Name | Type |
|---|---|
T | extends Passable = Passable |
Defined in
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
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
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
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
PassStyle
Ƭ PassStyle: PrimitiveStyle | "copyRecord" | "copyArray" | "tagged" | "remotable" | "error" | "promise"
Defined in
PassStyleOf
Ƭ PassStyleOf: (passable: Passable) => PassStyle
Type declaration
▸ (passable): PassStyle
Parameters
| Name | Type |
|---|---|
passable | Passable |
Returns
Defined in
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
PassableCap
Ƭ PassableCap: Promise | RemotableObject
The authority-bearing leaves of a Passable's pass-by-copy superstructure.
Defined in
PrimitiveStyle
Ƭ PrimitiveStyle: "undefined" | "null" | "boolean" | "number" | "bigint" | "string" | "symbol"
Defined in
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
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
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
PASS_STYLE
• Const PASS_STYLE: typeof PASS_STYLE
Defined in
Functions
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
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
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
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
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
assertPassable
▸ assertPassable(val): void
Parameters
| Name | Type |
|---|---|
val | any |
Returns
void
Defined in
assertPassableError
▸ assertPassableError(err): asserts err is Error
Parameters
| Name | Type |
|---|---|
err | unknown |
Returns
asserts err is Error
Defined in
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
assertPassableSymbol
▸ assertPassableSymbol(sym): true
Parameters
| Name | Type |
|---|---|
sym | any |
Returns
true
Defined in
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
assertRemotable
▸ assertRemotable(remotable, optNameOfRemotable): asserts remotable is any
Parameters
| Name | Type |
|---|---|
remotable | any |
optNameOfRemotable | undefined | string |
Returns
asserts remotable is any
Defined in
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
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
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
getInterfaceOf
▸ getInterfaceOf(maybeRemotable): undefined | string
Parameters
| Name | Type | Description |
|---|---|---|
maybeRemotable | any | the value to check |
Returns
undefined | string
Defined in
getTag
▸ getTag(tagRecord): any
Parameters
| Name | Type |
|---|---|
tagRecord | any |
Returns
any
Defined in
hasOwnPropertyOf
▸ hasOwnPropertyOf(obj, prop): any
Parameters
| Name | Type |
|---|---|
obj | any |
prop | any |
Returns
any
Defined in
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
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
isObject
▸ isObject(val): boolean
Parameters
| Name | Type |
|---|---|
val | any |
Returns
boolean
Defined in
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
isPassableError
▸ isPassableError(err): err is Error
Parameters
| Name | Type |
|---|---|
err | unknown |
Returns
err is Error
Defined in
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
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
isRemotable
▸ isRemotable(remotable): remotable is any
Check whether the argument is a remotable.
Parameters
| Name | Type |
|---|---|
remotable | any |
Returns
remotable is any
Defined in
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
makeTagged
▸ makeTagged(tag, payload): any
Parameters
| Name | Type |
|---|---|
tag | any |
payload | any |
Returns
any
Defined in
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
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
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
Defined in
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
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