Version 4 is an ES module and requires Node.js 22.12 or later. CommonJS
consumers on those versions can still load it with a plain require().
The library also runs in browsers: it bundles cleanly with standard
tooling (esbuild, webpack, etc.) and is tested in Chromium, Firefox, and
WebKit.
Installation
npm install activitystrea.ms
Usage
Use as.import() to turn a plain JavaScript Activity Streams document into a
model object. This works for documents you receive and documents you create.
Model type names are expanded IRIs. Object-valued properties are iterable
collections of references or embedded objects; .first retrieves the first
value. Text properties such as content are language values, read with .get().
Language maps can be supplied directly in the imported document:
const note = await as.import({ '@context': 'https://www.w3.org/ns/activitystreams', type: 'Note', contentMap: { en: 'Hello, world!', fr: 'Bonjour tout le monde !' }})console.log(note.content.get('fr')) // 'Bonjour tout le monde !'
Exporting and serializing
export() returns a plain JavaScript document after JSON-LD compaction.
write() returns a JSON string, and prettyWrite() returns indented JSON.
All three methods are asynchronous.
To retain an imported document's original context when exporting, pass
{ useOriginalContext: true } to export(), write(), or prettyWrite().
Custom context documents can be registered with as.registerContext() for
offline resolution; see the API reference below.
Browser use
Bundle the library and its dependencies with browser tooling such as esbuild
or webpack. The source dependency graph still includes CommonJS packages, so
resolving package names alone is insufficient for direct browser imports.
Browser tests that import source modules need the same dependency
transformation as the application build.
The fluent builder interface remains supported as an alternative; see
Builder interface below.
Builder interface
The builder interface uses a fluent factory pattern for creating AS objects. There are
factory methods for each of the main types of objects defined by the Activity
Streams 2.0 vocabulary. Each takes an optional array of types that will be set
on the object. If the [types] is unspecified, a default will be assigned
depending on the object being created. Each of the factory methods returns a
builder specific to the kind of object being generated. Once the object has
been built, call the get method to return the generated object.
as.object([types])
as.activity([types])
as.collection([types])
as.orderedCollection([types])
as.collectionPage([types])
as.orderedCollectionPage([types])
as.link([types])
as.accept([types])
as.tentativeAccept([types])
as.add([types])
as.arrive([types])
as.create([types])
as.delete([types])
as.follow([types])
as.ignore([types])
as.join([types])
as.leave([types])
as.like([types])
as.offer([types])
as.invite([types])
as.reject([types])
as.tentativeReject([types])
as.remove([types])
as.undo([types])
as.update([types])
as.view([types])
as.listen([types])
as.read([types])
as.move([types])
as.travel([types])
as.announce([types])
as.block([types])
as.flag([types])
as.dislike([types])
as.application([types])
as.group([types])
as.person([types])
as.organization([types])
as.service([types])
as.article([types])
as.document([types])
as.relationship([types])
as.profile([types])
as.audio([types])
as.image([types])
as.video([types])
as.note([types])
as.page([types])
as.question([types])
as.event([types])
as.place([types])
as.mention([types])
as.tombstone([types])
The object returned by get() is a read-only view of the Activity Stream
object. It will have property methods that are specific to the object's type.
You can export the built object as an ordinary Javascript object using the
export method. This will generate a JSON-LD compliant Javascript object.
import as from 'activitystrea.ms'const note = as.note() .name('foo') .content('this is a simple note') .get()console.log(note.name.valueOf())console.log(note.content.valueOf())console.log(note.type)
import as from 'activitystrea.ms'const obj = await as.note() .name('foo') .content('this is a simple note') .get() .export()// obj is an ordinary javascript objectconsole.log(obj.type)console.log(obj.name)console.log(obj.content)
To serialize the Activity Streams object out as JSON, use the write or
prettyWrite methods
import as from 'activitystrea.ms'const doc = await as.note() .name('foo') .content('this is a simple note') .write()
import as from 'activitystrea.ms'const doc = await as.note() .name('foo') .content('this is a simple note') .prettyWrite()
Note that the export, write, and prettyWrite methods are all async and return promises.
This is largely because of the JSON-LD processing that's happening under the covers.
API
import as from 'activitystrea.ms'
The base module. (CommonJS consumers on Node 22.12+ can use
const as = require('activitystrea.ms') instead.)
Imports the specified JavaScript object obj, performing JSON-LD expansion as necessary. Returns a promise that resolves to the imported as.models.Object.
Registers a JSON-LD context document for offline resolution. When an
imported document's @context includes the registered URL, the local copy
is used instead of fetching it over the network. The AS2 context and
https://w3id.org/security/v1 are pre-registered.
as.registerContext('https://example.com/context', { '@context': { ex: 'https://example.com/context#', bar: 'ex:bar' }})
as.mediaType
Set to a constant value of application/activity+json
Builder factories
<as.models.Object.Builder> as.object([types])
Returns a new as.models.Object.Builder instance.
<as.models.Activity.Builder> as.activity([types])
Returns a new as.models.Activity.Builder instance.
Returns the value of the JSON-LD @type property. If @type has only a single value, then a single JavaScript string will be returned. If the @type has multiple values, a JavaScript Array will be returned. If the @type is not specified, undefined will be returned.
Returns true if the object has a value for the specified key
Method: <any> as.models.Base.prototype.get(key)
Returns the value for the specified key. The return value will vary based on the property being requested. The return value can be a JavaScript primitive, a as.models.Base instance, or an Iterable of JavaScript primitives or as.models.Base instances. Will returned undefined if the no value is specified for the given key
Exports the object by performing a JSON-LD compaction. If export fails, the promise will reject with the error. If the export succeeds, the promise will resolve with the exported JavaScript object.
Write the object out to a JSON-LD string. If writing fails, the promise will reject with the error. If the write succeeds, the promise will resolve with the JSON-LD string.
Write the object out to an indented JSON-LD string. If writing fails, the promise will reject with the error. If the write succeeds, the promise will resolve with the JSON-LD string.
Returns a new as.models.Base.Builder instance that can be used to modify
this object. Note that model objects memoize property values on first
access, so modify() should only be used on objects that have not been
read from yet.
Returns a function that can be used to create new as.models.Base.Builder instances using this object as a template. The new Builder will be pre-filled with the properties already specified on this object.
The base Builder interface. This is not intended to be used directly by developers. Most of the methods on the Builder instances return a reference
back to the Builder itself allowing methods to be chained.
The base class for all Activity Streams 2.0 Object instances. Inherits from as.models.Base
Property: as.models.Object.prototype.attachment
Returns the value of the https://www.w3.org/ns/activitystreams#attachment property. Will be either undefined or an Iterable of as.model.Base instances.
Returns the value of the https://www.w3.org/ns/activitystreams#attributedTo property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Object.prototype.content
Returns the value of the https://www.w3.org/ns/activitystreams#content property. Will be either undefined or a as.models.LanguageValue.
Property: as.models.Object.prototype.context
Returns the value of the https://www.w3.org/ns/activitystreams#context property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Object.prototype.name
Returns the value of the https://www.w3.org/ns/activitystreams#name property. Will be either undefined or a as.models.LanguageValue.
Property: as.models.Object.prototype.summary
Returns the value of the https://www.w3.org/ns/activitystreams#summary property. Will be either undefined or a as.models.LanguageValue.
Property: as.models.Object.prototype.endTime
Returns the value of the https://www.w3.org/ns/activitystreams#endTime property. Will be either undefined or a JavaScript Date object.
Property: as.models.Object.prototype.published
Returns the value of the https://www.w3.org/ns/activitystreams#published property. Will be either undefined or a JavaScript Date object.
Property: as.models.Object.prototype.startTime
Returns the value of the https://www.w3.org/ns/activitystreams#startTime property. Will be either undefined or a JavaScript Date object.
Property: as.models.Object.prototype.updated
Returns the value of the https://www.w3.org/ns/activitystreams#updated property. Will be either undefined or a JavaScript Date object.
Property: as.models.Object.prototype.generator
Returns the value of the https://www.w3.org/ns/activitystreams#generator property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Object.prototype.icon
Returns the value of the https://www.w3.org/ns/activitystreams#icon property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Object.prototype.image
Returns the value of the https://www.w3.org/ns/activitystreams#image property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Object.prototype.inReplyTo
Returns the value of the https://www.w3.org/ns/activitystreams#inReplyTo property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Object.prototype.location
Returns the value of the https://www.w3.org/ns/activitystreams#location property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Object.prototype.preview
Returns the value of the https://www.w3.org/ns/activitystreams#preview property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Object.prototype.replies
Returns the value of the https://www.w3.org/ns/activitystreams#replies property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Object.prototype.audience
Returns the value of the https://www.w3.org/ns/activitystreams#audience property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Object.prototype.tag
Returns the value of the https://www.w3.org/ns/activitystreams#tag property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Object.prototype.url
Returns the value of the https://www.w3.org/ns/activitystreams#url property. Will be either undefined or an Iterable of as.model.Link instances.
Property: as.models.Object.prototype.to
Returns the value of the https://www.w3.org/ns/activitystreams#to property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Object.prototype.bto
Returns the value of the https://www.w3.org/ns/activitystreams#bto property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Object.prototype.cc
Returns the value of the https://www.w3.org/ns/activitystreams#cc property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Object.prototype.bcc
Returns the value of the https://www.w3.org/ns/activitystreams#bcc property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Object.prototype.duration
Returns the value of the https://www.w3.org/ns/activitystreams#duration property. Will be either undefined or a frozen plain object with the same numeric properties as a Temporal.Duration: years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds. All properties are always present, with 0 for unspecified units. Negative durations have negative values. Malformed duration strings yield undefined.
Sets an optional language-tagged value for the https://www.w3.org/ns/activitystreams#content property. To set
language-tagged values, use the as.langmap method to create a
LanguageValue.Builder.
Sets the value of the https://www.w3.org/ns/activitystreams#duration property.
The value is either a number of seconds or an ISO 8601 duration string
(e.g. 'PT1H30M').
Class: as.models.Activity > as.models.Object
Base class for all Activity Streams 2.0 Activity instances. Inherits from as.models.Object
Property: as.models.Activity.prototype.actor
Returns the value of the https://www.w3.org/ns/activitystreams#actor property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Activity.prototype.object
Returns the value of the https://www.w3.org/ns/activitystreams#object property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Activity.prototype.target
Returns the value of the https://www.w3.org/ns/activitystreams#target property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Activity.prototype.result
Returns the value of the https://www.w3.org/ns/activitystreams#result property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Activity.prototype.origin
Returns the value of the https://www.w3.org/ns/activitystreams#origin property. Will be either undefined or an Iterable of as.model.Base instances.
Property: as.models.Activity.prototype.instrument
Returns the value of the https://www.w3.org/ns/activitystreams#instrument property. Will be either undefined or an Iterable of as.model.Base instances.
Returns the value of the https://www.w3.org/ns/activitystreams#totalItems property. The value will either be undefined or a numeric integer greater than or equal to zero.
Property: as.models.Collection.prototype.current
Returns the value of the https://www.w3.org/ns/activitystreams#current property. The value will either be undefined or a as.models.Base instance.
Property: as.models.Collection.prototype.last
Returns the value of the https://www.w3.org/ns/activitystreams#last property. The value will either be undefined or a as.models.Base instance.
Property: as.models.Collection.prototype.first
Returns the value of the https://www.w3.org/ns/activitystreams#first property. The value will either be undefined or a as.models.Base instance.
Property: as.models.Collection.prototype.items
Returns the value of the https://www.w3.org/ns/activitystreams#items property as an Iterable of as.models.Base instances.
Returns the value of the https://www.w3.org/ns/activitystreams#startIndex property. The value will either be undefined or a numeric integer greater than or equal to zero.
The base class for all as.models.OrderedCollectionPage builders. Inherits from both as.models.CollectionPage.Builder and as.models.OrderedCollection.Builder.
Sets the value of the https://www.w3.org/ns/activitystreams#startIndex property. The value must be a numeric integer greater than or equal to zero.
Class: as.models.Link > as.models.Base
The base class for all Activity Streams 2.0 Links. Inherits from as.models.Base
Property: as.models.Link.prototype.href
Returns the value of the https://www.w3.org/ns/activitystreams#href property. The value will either be undefined or a URL string.
Property: as.models.Link.prototype.rel
Returns the value of the https://www.w3.org/ns/activitystreams#rel property. The value will either be undefined or an Iterable of strings.
Property: as.models.Link.prototype.mediaType
Returns the value of the https://www.w3.org/ns/activitystreams#mediaType property. The value will either be undefined or a MIME Media Type.
Property: as.models.Link.prototype.name
Returns the value of the https://www.w3.org/ns/activitystreams#name property as a LanguageValue.
Property: as.models.Link.prototype.hreflang
Returns the value of the https://www.w3.org/ns/activitystreams#hreflang property. The value will either be undefined or a BCP 47 Language Tag.
Property: as.models.Link.prototype.height
Returns the value of the https://www.w3.org/ns/activitystreams#height property.The value will either be undefined or a numeric integer greater than or equal to zero.
Property: as.models.Link.prototype.width
Returns the value of the https://www.w3.org/ns/activitystreams#width property.The value will either be undefined or a numeric integer greater than or equal to zero.
Sets the value of the https://www.w3.org/ns/activitystreams#width property.
The value is a numeric integer greater than or equal to zero.
Class: as.models.Place > as.models.Object
The base class for all Activity Streams 2.0 Place objects. Inherits from as.models.Object
Property: as.models.Place.prototype.accuracy
Returns the value of the https://www.w3.org/ns/activitystreams#accuracy property. The value will either be undefined or a numeric integer in the range 0 <= n <= 100.
Property: as.models.Place.prototype.altitude
Returns the value of the https://www.w3.org/ns/activitystreams#altitude property. The value will be either undefined or a numeric float.
Property: as.models.Place.prototype.latitude
Returns the value of the https://www.w3.org/ns/activitystreams#latitude property. The value will be either undefined or a numeric float in the range -90.0 <= n <= 90.0.
Property: as.models.Place.prototype.longitude
Returns the value of the https://www.w3.org/ns/activitystreams#longitude property. The value will be either undefined or a numeric float in the range -180.0 <= n <= 180.0.
Property: as.models.Place.prototype.radius
Returns the value of the https://www.w3.org/ns/activitystreams#radius property.
The value will be either undefined or a numeric float greater than or equal to zero.
Property: as.models.Place.prototype.units
Returns the value of the https://www.w3.org/ns/activitystreams#units property. The value will be one of: cm, feet, inches, km, m, miles, or any absolute URI.
Sets the value of the https://www.w3.org/ns/activitystreams#units property.
The value must be one of: cm, feet, inches, km, m, miles, or any absolute URI.
Class: as.models.Profile > as.models.Object
The base class for all Activity Streams 2.0 Profile objects. Inherits from as.models.Object
Sets the value of the https://www.w3.org/ns/activitystreams#describes property.
Class: as.models.Question > as.models.Activity
The base class for all Activity Streams 2.0 Question objects. Inherits from
as.models.Activity;
Property: as.models.Question.prototype.anyOf
Returns the value of the https://www.w3.org/ns/activitystreams#anyOf property.
The value will either be undefined or an Iterable of as.models.Base objects.
Property: as.models.Question.prototype.oneOf
Returns the value of the https://www.w3.org/ns/activitystreams#oneOf property.
The value will either be undefined or an Iterable of as.models.Base objects.
Returns the value of the https://www.w3.org/ns/activitystreams#relationship property. The value will either be undefined or an Iterable of as.models.Base objects.
Property: as.models.Relationship.prototype.object
Returns the value of the https://www.w3.org/ns/activitystreams#object property. The value will either be undefined or an Iterable of as.models.Base objects.
Language tags are matched case-insensitively, using RFC 4647 lookup with a
prefix-match fallback (asking for en finds an en-US entry, and asking
for en-US-x-foo finds an en-US entry). The default language comes from
the LANG environment variable in Node.js, navigator.language in
browsers, and falls back to en-US.