# jsonld-streaming-serializer

> A fast and lightweight streaming JSON-LD serializer

Latest version **4.0.0** (published 2025-01-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install jsonld-streaming-serializer
pnpm add jsonld-streaming-serializer
yarn add jsonld-streaming-serializer
bun add jsonld-streaming-serializer
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2025-01-08 |
| First published | 2019-04-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 77.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 41 |
| Author | Ruben Taelman |
| Maintainers | rubensworks |
| Keywords | json, linked data, semantic web, json-ld, jsonld, rdf, rdfjs, streaming, asynchronous |

## Links

- npm: https://www.npmjs.com/package/jsonld-streaming-serializer
- Repository: https://github.com/rubensworks/jsonld-streaming-serializer.js
- Homepage: https://github.com/rubensworks/jsonld-streaming-serializer.js#readme
- Issues: https://github.com/rubensworks/jsonld-streaming-serializer.js/issues
- Funding: https://github.com/sponsors/rubensworks/
- npm.io page: https://npm.io/package/jsonld-streaming-serializer

## Dependencies (5)

- [buffer](https://npm.io/package/buffer.md) ^6.0.3
- [@rdfjs/types](https://npm.io/package/@rdfjs/types.md) ^2.0.0
- [readable-stream](https://npm.io/package/readable-stream.md) ^4.0.0
- [jsonld-context-parser](https://npm.io/package/jsonld-context-parser.md) ^3.0.0
- [@types/readable-stream](https://npm.io/package/@types/readable-stream.md) ^4.0.0

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 4.0.0 (latest) — 2025-01-08
- 3.0.1 — 2024-09-27
- 3.0.0 — 2024-09-27
- 2.1.0 — 2022-11-25
- 2.0.1 — 2022-11-09
- 2.0.0 — 2022-07-14
- 1.3.0 — 2021-08-11
- 1.2.0 — 2020-09-15
- 1.1.1 — 2020-09-02
- 1.1.0 — 2020-04-03
- 1.0.1 — 2019-04-03
- 1.0.0 — 2019-04-03

## README

# JSON-LD Streaming Serializer

[![Build status](https://github.com/rubensworks/jsonld-streaming-serializer.js/workflows/CI/badge.svg)](https://github.com/rubensworks/jsonld-streaming-serializer.js/actions?query=workflow%3ACI)
[![Coverage Status](https://coveralls.io/repos/github/rubensworks/jsonld-streaming-serializer.js/badge.svg?branch=master)](https://coveralls.io/github/rubensworks/jsonld-streaming-serializer.js?branch=master)
[![npm version](https://badge.fury.io/js/jsonld-streaming-serializer.svg)](https://www.npmjs.com/package/jsonld-streaming-serializer)

A fast and lightweight _streaming_ [JSON-LD](https://json-ld.org/) serializer,
with [RDFJS](https://github.com/rdfjs/representation-task-force/) representations of RDF terms, quads and triples.

The streaming nature allows JSON-LD chunks to be emitted _as soon as possible_, and RDF streams _larger than memory_ to be serialized.

## Installation

```bash
$ npm install jsonld-streaming-serializer
```

or

```bash
$ yarn add jsonld-streaming-serializer
```

This package also works out-of-the-box in browsers via tools such as [webpack](https://webpack.js.org/) and [browserify](http://browserify.org/).

## Require

```javascript
import {JsonLdSerializer} from "jsonld-streaming-serializer";
```

_or_

```javascript
const JsonLdSerializer = require("jsonld-streaming-serializer").JsonLdSerializer;
```


## Usage

`JsonLdSerializer` is a Node [Transform stream](https://nodejs.org/api/stream.html#stream_class_stream_transform)
that takes in [RDFJS](http://rdf.js.org/) quads,
and outputs string chunks of JSON-LD data.

It can be used to [`pipe`](https://nodejs.org/api/stream.html#stream_readable_pipe_destination_options) [quad streams](http://rdf.js.org/stream-spec/#stream-interface) to,
or you can write [RDF quads](http://rdf.js.org/data-model-spec/#quad-interface) into the serializer directly.

### Pretty-print given triples to the console

By default, this parser will serialize everything as compact as possible on a single line (but chunked).
Using the `space` option, the output can be pretty-printed for improving human-readability.

```javascript
const dataFactory = require('@rdfjs/data-model');
const mySerializer = new JsonLdSerializer({ space: '  ' });
mySerializer.pipe(process.stdout);

mySerializer.write(dataFactory.triple(
  dataFactory.namedNode('http://ex.org/s1'),
  dataFactory.namedNode('http://ex.org/p1'),
  dataFactory.namedNode('http://ex.org/o1'),
));
mySerializer.write(dataFactory.triple(
  dataFactory.namedNode('http://ex.org/s1'),
  dataFactory.namedNode('http://ex.org/p1'),
  dataFactory.namedNode('http://ex.org/o2'),
));
mySerializer.end();
```

### Pipe a stream of triples

```javascript
const mySerializer = new JsonLdSerializer();

myTripleStream
    .pipe(mySerializer)
    .pipe(process.stdout);
```

### Import streams

This serializer implements the RDFJS [Sink interface](https://rdf.js.org/#sink-interface),
which makes it possible to alternatively parse streams using the `import` method.

```javascript
const mySerializer = new JsonLdSerializer();

mySerializer.import(myTripleStream)
  .on('data', console.log)
  .on('error', console.error)
  .on('end', () => console.log('All triples were serialized!'));
```

### Write @list's

Since RDF lists can not be detected in a streaming-way
without waiting until the stream ends,
this serializer offers `list()` an alternative way to serialize RDF list
using JSON-LD's `@list` keyword.

```javascript
const dataFactory = require('@rdfjs/data-model');
const mySerializer = new JsonLdSerializer({ space: '  ' });
mySerializer.pipe(process.stdout);

mySerializer.write(dataFactory.triple(
  dataFactory.namedNode('http://ex.org/s1'),
  dataFactory.namedNode('http://ex.org/p1'),
  await mySerializer.list([
    dataFactory.namedNode('http://ex.org/o1'),
    dataFactory.namedNode('http://ex.org/o2'),
    dataFactory.namedNode('http://ex.org/o3'),
  ]),
));
mySerializer.end();
```

### Compact with a context

Optionally, a context (or baseIRI) can be provided to the serializer,
which will make the parser output this context into the stream (unless `excludeContext` is false),
and all terms will attempted to be compacted based on this context.

****External context:****
```javascript
const mySerializer = new JsonLdSerializer({
  context: 'http://schema.org/',
});
```

****Inline context:****
```javascript
const mySerializer = new JsonLdSerializer({
  context: {
    termA: 'http://ex.org/a',
    termB: 'http://ex.org/B',
  },
});
```

****Array context:****
```javascript
const mySerializer = new JsonLdSerializer({
  context: [
    {
      termA: 'http://ex.org/a',
      termB: 'http://ex.org/B',
    },
    'http://schema.org/'
  ],
});
```

## Restrictions

While this serializer outputs valid JSON-LD 1.1 and JSON-LD-star,
it does not fully comply with all the specification tests,
as these assume non-streaming processing.

As such, this serializer has the following restrictions:

* RDF lists are not converted to `@list` arrays. However, the `list()` helper method can be manually called to achieve this.
* `rdfDirection: 'compound-literal'` is not supported, as this may require keeping the whole stream in-memory.
* No deduplication of triples, as this would require keeping the whole stream in-memory.

## Configuration

Optionally, the following parameters can be set in the `JsonLdSerializer` constructor:

* `space`: An optional indentation string that should be used when stringifying JSON. _(Default: `null`)_
* `context`: An optional root context to use while serializing. It will also try to compact as many terms as possible based on the compacting capabilities of [jsonld-context-parser](https://github.com/rubensworks/jsonld-context-parser.js). This context will be emitted to the stream, unless `excludeContext` is set to false. _(Default: `null`)_
* `baseIRI`: An optional base IRI for compacting terms. It will enhance the context with a `@base` entry. This will also cause a context to be emitted unless `excludeContext` is set to false. _(Default: `null`)_
* `excludeContext`: If a `context` or `baseIRI` is set, the context will be emitted into the output stream, unless this option is set to `true`. _(Default: `false`)_
* `useRdfType`: An optional boolean indicating if rdf:type predicates should be emitted directly, instead of @type. _(Default: `false`)_
* `useNativeTypes`: An optional boolean indicating if literals should be converted to primitive types, such as booleans and integers. _(Default: `false`)_
* `rdfDirection`: The [mode](https://w3c.github.io/json-ld-api/#dom-jsonldoptions-rdfdirection) under which `@direction` should be handled. If undefined, `@direction` is considered a regular RDF 1.2 literal with a base direction. Alternatively, it can be set to either `'i18n-datatype'` or `'compound-literal'` _(Default: `undefined`)_

```javascript
new JsonLdSerializer({
  space: '  ',
  context: 'https://schema.org/',
  baseIRI: 'http://example.org/',
  excludeContext: true,
  useRdfType: true,
  useNativeTypes: true,
  rdfDirection: 'i18n-datatype',
});
```

## License
This software is written by [Ruben Taelman](http://rubensworks.net/).

This code is released under the [MIT license](http://opensource.org/licenses/MIT).

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