# @endo/pass-style

> Defines the taxonomy of Passable objects.

Latest version **2.0.1** (published 2026-08-17) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @endo/pass-style
pnpm add @endo/pass-style
yarn add @endo/pass-style
bun add @endo/pass-style
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2026-08-17 |
| First published | 2023-03-07 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 6 |
| Unpacked size | 171 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1053 |
| Author | Endo contributors |
| Maintainers | kriskowal, michaelfig, erights, warner, mhofman, boneskull, naugtur, turadga, kriscendobot |

## Links

- npm: https://www.npmjs.com/package/@endo/pass-style
- Repository: https://github.com/endojs/endo
- Homepage: https://github.com/endojs/endo/tree/master/packages/pass-style#readme
- Issues: https://github.com/endojs/endo/issues
- npm.io page: https://npm.io/package/@endo/pass-style

## Dependencies (6)

- [@endo/common](https://npm.io/package/@endo/common.md) ^1.4.0
- [@endo/errors](https://npm.io/package/@endo/errors.md) ^1.3.1
- [@endo/harden](https://npm.io/package/@endo/harden.md) ^1.1.0
- [@endo/env-options](https://npm.io/package/@endo/env-options.md) ^1.1.11
- [@endo/promise-kit](https://npm.io/package/@endo/promise-kit.md) ^1.2.1
- [@endo/eventual-send](https://npm.io/package/@endo/eventual-send.md) ^1.5.0

## Recent versions

- 2.0.1 (latest) — 2026-08-17
- 1.8.2 (latest-v1) — 2026-08-13
- 1.8.1 — 2026-06-12
- 1.8.0 — 2026-04-17
- 1.7.0 — 2026-02-26
- 1.6.3 — 2025-07-12
- 1.6.2 — 2025-06-17
- 1.6.1 — 2025-06-17
- 1.6.0 — 2025-06-02
- 1.5.0 — 2025-03-24
- 1.4.8 — 2025-01-24
- 1.4.7 — 2024-11-13
- 1.4.6 — 2024-10-22
- 2.0.0 — 2024-10-22
- 1.4.4 — 2024-10-10
- … 17 more at https://npm.io/package/@endo/pass-style/versions

## README

# `@endo/pass-style`

Defines what data can be passed between vats in an object-capability system.

## Overview

The **@endo/pass-style** package defines the `Passable` type and provides the
`passStyleOf()` function for classifying JavaScript values according to their
`PassStyle`.
This classification determines how values can safely be passed between isolated
compartments or across network boundaries.

Every passable value has exactly one pass style from a fixed set of
possibilities.
The key distinction is between **pass-by-copy** (the value itself is copied)
and **Pass-by-reference**.

## Pass Styles

| Pass Style | Category | Description | Examples |
|------------|----------|-------------|----------|
| `'null'` | Primitive | The null value | `null` |
| `'undefined'` | Primitive | The undefined value | `undefined` |
| `'boolean'` | Primitive | Boolean primitives | `true`, `false` |
| `'number'` | Primitive | IEEE 754 floats | `42`, `3.14`, `NaN`, `Infinity` |
| `'bigint'` | Primitive | Arbitrary-precision integers | `123n`, `-456n` |
| `'string'` | Primitive | Well-formed strings | `'hello'`, `''` |
| `'symbol'` | Primitive | Registered/well-known symbols | `Symbol.iterator` |
| `'copyArray'` | Pass-by-copy | Frozen arrays of passables | `harden([1, 2, 3])` |
| `'copyRecord'` | Pass-by-copy | Frozen plain objects | `harden({ x: 10 })` |
| `'remotable'` | Pass-by-presence | Far objects & remote presences | `Far('Counter', {...})` |
| `'tagged'` | Extension | Domain-specific types | `makeTagged('copySet', [...])` |
| `'error'` | Pass-by-presence | Error objects | `harden(Error('failed'))` |
| `'promise'` | Pass-by-presence | Promise objects | `Promise.resolve(42)` |

## Core Functions

### passStyleOf(value)

Classifies a value's pass style.
Throws if the value is not passable.

```javascript
import { passStyleOf } from '@endo/pass-style';

passStyleOf(42);                    // 'number'
passStyleOf(harden([1, 2]));        // 'copyArray'
passStyleOf(harden({ x: 1 }));      // 'copyRecord'
passStyleOf(Promise.resolve());     // 'promise'

// Throws for non-passable values
passStyleOf({ x: 1 });  // Error: not frozen
```

### isPassable(value)

Boolean test for passability.
Returns `true` if the value is passable, `false` otherwise.

```javascript
import { isPassable } from '@endo/pass-style';

isPassable(42);                // true
isPassable(harden([1, 2]));    // true
isPassable({ x: 1 });          // false - not frozen
isPassable(harden({ x: 1 }));  // true
```

Use `isPassable()` when you want a boolean result.
Use `passStyleOf()` when you need the specific pass style or want detailed
error messages.

### Far(iface, methods)

Creates a remotable object that can be passed by reference.

```javascript
import { Far } from '@endo/pass-style';

const counter = Far('Counter', {
  increment() { return count += 1; },
  getValue() { return count; }
});

passStyleOf(counter);  // 'remotable'
```

**Note:** Far objects are remotable but don't validate their inputs.
For defensive objects with automatic input validation, see
[@endo/exo](../exo/README.md).

### makeTagged(tag, payload)

Creates a CopyTagged object, the extension point for domain-specific data
types.

```javascript
import { makeTagged } from '@endo/pass-style';

const tagged = makeTagged('customType', { data: 42 });
passStyleOf(tagged);  // 'tagged'
```

Tagged objects are used internally by [@endo/patterns](../patterns/README.md)
to implement CopySet, CopyBag, and CopyMap.

## Passable Values

A value is passable if it meets these requirements:

1. **Primitives** are always passable (except unregistered symbols)
2. **Objects must be frozen** via `harden()` from `@endo/pass-style` or `ses`
3. **No cyclic references** in pass-by-copy structures (copyArray, copyRecord,
   tagged)
4. **Strings must be well-formed** (no unpaired surrogates)
5. **Symbols must tentatively be created using `passableSymbolForName()`** from
   `@endo/pass-style`.

```javascript
// Passable - frozen array of primitives
const data = harden([1, 2, 3]);

// NOT passable - not frozen
const mutable = [1, 2, 3];

// NOT passable - cyclic reference
const cyclic = harden([]);
cyclic.push(cyclic);
```

## Pass-by-Copy vs Pass-by-Presence

### Pass-by-Copy

The value itself is copied when passed.
Changes to the original don't affect copies.

**Use for:** Immutable data, configurations, messages, small structures

**Pass styles:** primitives, copyArray, copyRecord, tagged

```javascript
const config = harden({
  timeout: 5000,
  retries: 3
});

// When passed, config is copied
// The recipient gets a separate copy
```

### Pass-by-reference

A reference is passed.
The object remains in its original location.

**Use for:** Objects with behavior, mutable state, capabilities, large objects

**Pass styles:** remotable, promise, error

```javascript
const service = Far('Service', {
  getData() { return data; }
});

// When passed, only a reference is passed
// Method calls are forwarded to the original object
```

## Type Guards

The package provides type guards for common pass styles:

```javascript
import {
  isRecord, assertRecord,
  isCopyArray, assertCopyArray,
  isRemotable, assertRemotable,
  isAtom, assertAtom
} from '@endo/pass-style';

// Boolean checks
if (isRecord(value)) {
  // value is a CopyRecord
}

// Assertions (throw if false)
assertRemotable(obj);
// obj is guaranteed to be a remotable
```

## Integration with Endo Packages

- **Validation**: [@endo/patterns](../patterns/README.md) - Pattern matching to
  validate passables
- **Defensive Objects**: [@endo/exo](../exo/README.md) - Exos combine Far with
  pattern validation
- **Communication**: [@endo/eventual-send](../eventual-send/README.md) - Send
  messages using E() proxy
- **Serialization**: [@endo/marshal](../marshal/README.md) - Encode passables
  for transmission

**Complete Tutorial**: See [Message Passing](../../docs/message-passing.md) for
a comprehensive guide showing how pass-style works with patterns, exo, and
eventual-send.

## Deep Dives

For implementation details:
- [CopyRecord guarantees](./doc/copyRecord-guarantees.md) - Detailed validation
  guarantees for CopyRecord
- [CopyArray guarantees](./doc/copyArray-guarantees.md) - Detailed validation
  guarantees for CopyArray
- [Enumerating properties](./doc/enumerating-properties.md) - Property
  enumeration semantics
- [Type definitions](./src/types.js) - Complete TypeScript type definitions

---
_Source: https://npm.io/package/@endo/pass-style · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._