# @ipld/block

> IPLD Block interface

Latest version **6.0.4** (published 2020-09-13) · (Apache-2.0 AND MIT) license · 0 weekly downloads

## Install

```sh
npm install @ipld/block
pnpm add @ipld/block
yarn add @ipld/block
bun add @ipld/block
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 6.0.4 |
| Published | 2020-09-13 |
| First published | 2019-05-19 |
| Weekly downloads | 0 |
| License | (Apache-2.0 AND MIT) |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 21.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6 |
| Author | Mikeal Rogers |
| Maintainers | vmx, mikeal, daviddias |

## Links

- npm: https://www.npmjs.com/package/@ipld/block
- Repository: https://github.com/ipld/js-block
- Homepage: https://github.com/ipld/js-block#readme
- Issues: https://github.com/ipld/js-block/issues
- npm.io page: https://npm.io/package/@ipld/block

## Dependencies (4)

- [class-is](https://npm.io/package/class-is.md) ^1.1.0
- [multiformats](https://npm.io/package/multiformats.md) ^3.0.3
- [@ipld/dag-cbor](https://npm.io/package/@ipld/dag-cbor.md) 1.1.11
- [lodash.transform](https://npm.io/package/lodash.transform.md) ^4.6.0

## Recent versions

- 6.0.4 (latest) — 2020-09-13
- 6.0.3 — 2020-08-20
- 6.0.2 — 2020-08-18
- 6.0.1 — 2020-07-20
- 6.0.0 — 2020-07-19
- 5.1.1 — 2020-06-24
- 5.1.0 — 2020-06-24
- 5.0.0 — 2020-06-23
- 4.0.2 — 2020-04-30
- 4.0.1 — 2020-04-24
- 4.0.0 — 2020-04-09
- 3.0.0 — 2020-04-03
- 2.2.1 — 2020-04-01
- 2.2.0 — 2020-03-22
- 2.1.4 — 2020-03-10
- … 14 more at https://npm.io/package/@ipld/block/versions

## README

# Block API

The `Block` API is the single endpoint for authoring IPLD data structures. Unless you're
implementing a new codec you can get everything you need from the Block API: encoding, 
decoding, cid creation w/ hashing.

```javascript
import Block from '@ipld/block/defaults'

const b1 = Block.encoder({ hello: 'world' }, 'dag-cbor')

// link between blocks
const b2 = Block.encoder({ head: await b1.cid() }, 'dag-cbor')

// write to a standard key value store
for (const block of [b1, b2]) {
  const cid = await block.cid()
  await put(cid.toString('base64'), block.encode())
}

// write to a store that understands the Block interface
await Promise.all([put(b1), put(b2)])
```

## `Block.encoder(object, codec, algorithm = 'sha2-256')`

Create a Block instance from a native object.

The `cid` as well as encoding will not happen until requested
and then will be cached when appropriate.

```javascript
let block = Block.encoder({hello: 'world'}, 'dag-cbor')
```

Returns a `Block` instance.

## `Block.decoder(binary, codec, algorithm = 'sha2-256')`

Create a Block instance from an existing binary encoded block

The `cid` as well as decoding will not happen until requested
and then will be cached when appropriate.

```javascript
let block = Block.decoder(someBuffer, 'dag-cbor')
```

Returns a `Block` instance.

## `Block.create(binary, cid)`

Create a new block from the raw binary data and cid.

`cid` can be an instance of `CID` or a base encoded string of a cid.

Returns a `Block` instance.

## `Block(opts)`

Once a block instance is created the information represented in the block is considered
immutable.

### `block.decode()`

Returns decoded block data.

A new object is returned on every call that is copied from a cached version of
the decoded block. This means you are free to mutate the return value and
that we'll never do more than one actual block decode in the codec.

### `block.decodeUnsafe()`

Returns the cached block data directly.

**Waring: If you mutate the return value bad things will happen.**

This operation is very fast and useful as long as you can ensure the return value
will not be mutated.

### `block.cid()`

Promise that resolves to a `cid` instance. Cached after creation.

### `block.encode()`

Returns a `Buffer` instance encoded from the source input.

The first time the block is encoded it is cached indefinitely. This method returns
a new copied buffer that you are free to mutate.

### `block.encodeUnsafe()`

Returns a `Buffer` instance encoded from the source input.

**Warning: If you mutate the return value bad things will happen.**

This returns the internal cached versoin of the block encode. It's very fast
and useful if you are certain the buffer won't be mutated.

### `block.reader()`

Returns an instance of `Reader()` from the codec implementation.

### `block.validate()`

Returns true/false if the CID's multihash matches the given block.

If a CID hasn't been created yet it will return true since we know the hash will
match in our eventually created CID.

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