mostly comments2

packages/types/lib/Core/CoreObject.d.ts

@@ -18,8 +18,8 @@ export type CoreObjectProperties = {
     duration?: string;
     endTime?: Date;
     generator?: OrArray<EntityReference>;
-    icon?: ImageReference | LinkReference | Array<ImageReference | LinkReference>;
-    image?: ImageReference | LinkReference | Array<ImageReference | LinkReference>;
+    icon?: OrArray<ImageReference | LinkReference>;
+    image?: OrArray<ImageReference | LinkReference>;
     inReplyTo?: OrArray<EntityReference>;
     location?: OrArray<EntityReference>;
     mediaType?: string;

packages/types/lib/Core/Link.d.ts

@@ -15,8 +15,7 @@ export type LinkProperties = {
     width?: number;
 };
 export type BaseLink<T extends AnyLinkType> = BaseEntity<T> & LinkProperties;
-type LinkEntity = BaseLink<typeof LinkTypes.LINK>;
+export type LinkEntity = BaseLink<typeof LinkTypes.LINK>;
 export type Mention = BaseLink<typeof LinkTypes.MENTION>;
 export type Link = LinkEntity | Mention;
 export type LinkReference = URL | Link;
-export {};

packages/types/lib/Core/index.d.ts

@@ -2,12 +2,11 @@
 import { Link, Mention } from './Link';
 import { Actor } from '../Extended/Actor';
 import { Activity } from '../Extended/Activity';
-import { Collection, OrderedCollection } from '../Extended/Collection';
-import { CollectionPage, OrderedCollectionPage } from '../Extended/Collection';
+import { AnyCollectionOrCollectionPage } from '../Extended/Collection';
 import { ExtendedObject } from '../Extended';
 export { CoreObjectProperties } from './CoreObject';
 export type { Link, LinkReference, Mention } from './Link';
-export type CoreObject = ExtendedObject | Actor | Activity | Collection | OrderedCollection | CollectionPage | OrderedCollectionPage;
+export type CoreObject = ExtendedObject | Actor | Activity | AnyCollectionOrCollectionPage;
 export type CoreObjectReference = URL | CoreObject;
 export type Entity = CoreObject | Link | Mention;
 export type EntityReference = URL | Entity;

packages/types/lib/Extended/Collection.d.ts

@@ -10,6 +10,7 @@ export type AnyCollectionOrCollectionPageType = AnyCollectionType | AnyCollectio
 type CollectionProperties = {
     totalItems?: number;
     items?: OrArray<EntityReference>;
+    startIndex?: number;
     orderedItems?: OrArray<EntityReference>;
     current?: URL | CollectionPage | Link;
     first?: URL | CollectionPage | Link;
@@ -25,11 +26,7 @@ type CollectionPageProperties = {
 };
 type BaseCollectionPage<T extends AnyCollectionPageType> = BaseCollection<T> & CollectionPageProperties;
 export type CollectionPage = BaseCollectionPage<typeof CollectionPageTypes.COLLECTION_PAGE>;
-type OrderedCollectionPageProperties = {
-    startIndex?: number;
-    orderedItems?: OrArray<EntityReference>;
-};
-export type OrderedCollectionPage = BaseCollectionPage<typeof CollectionPageTypes.ORDERED_COLLECTION_PAGE> & OrderedCollectionPageProperties;
+export type OrderedCollectionPage = BaseCollectionPage<typeof CollectionPageTypes.ORDERED_COLLECTION_PAGE>;
 export type CollectionReference = URL | Collection;
 export type OrderedCollectionReference = URL | OrderedCollection;
 export type CollectionPageReference = URL | CollectionPage;
@@ -38,4 +35,6 @@ export type EitherCollection = Collection | OrderedCollection;
 export type EitherCollectionPage = CollectionPage | OrderedCollectionPage;
 export type EitherCollectionReference = URL | EitherCollection;
 export type EitherCollectionPageReference = URL | EitherCollectionPage;
+export type AnyCollectionOrCollectionPage = EitherCollection | EitherCollectionPage;
+export type AnyCollectionOrCollectionPageReference = URL | AnyCollectionOrCollectionPage;
 export {};

packages/types/lib/util/const.js.map

@@ -1 +1 @@
-{"version":3,"file":"const.js","sourceRoot":"","sources":["../../src/util/const.ts"],"names":[],"mappings":";;;AAAa,QAAA,mBAAmB,GAAG;IACjC,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,YAAY,EAAE,cAAc;IAC5B,SAAS,EAAE,WAAW;IACtB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;CACV,CAAC;AAEE,QAAA,SAAS,GAAG;IACvB,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;CACV,CAAC;AAEE,QAAA,UAAU,GAAG;IACxB,WAAW,EAAE,aAAa;IAC1B,KAAK,EAAE,OAAO;IACd,YAAY,EAAE,cAAc;IAC5B,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;CACV,CAAC;AAEE,QAAA,uBAAuB,GAAG;IACrC,MAAM,EAAE,QAAQ;IAChB,GAAG,EAAE,KAAK;IACV,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,gBAAgB,EAAE,iBAAiB;IACnC,gBAAgB,EAAE,iBAAiB;IACnC,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;CACJ,CAAC;AAEE,QAAA,yBAAyB,GAAG;IACvC,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;CACZ,CAAC;AAEE,QAAA,aAAa,GAAG;IAC3B,GAAG,+BAAuB;IAC1B,GAAG,iCAAyB;CACpB,CAAC;AAEE,QAAA,eAAe,GAAG;IAC7B,UAAU,EAAE,YAAY;IACxB,kBAAkB,EAAE,mBAAmB;CAC/B,CAAC;AAEE,QAAA,mBAAmB,GAAG;IACjC,eAAe,EAAE,gBAAgB;IACjC,uBAAuB,EAAE,uBAAuB;CACxC,CAAC;AAEE,QAAA,eAAe,GAAG;IAC7B,GAAG,2BAAmB;IACtB,GAAG,kBAAU;IACb,GAAG,qBAAa;IAChB,GAAG,uBAAe;IAClB,GAAG,2BAAmB;CACd,CAAC;AAEE,QAAA,QAAQ,GAAG;IACtB,GAAG,uBAAe;IAClB,GAAG,iBAAS;CACJ,CAAC"}
+{"version":3,"file":"const.js","sourceRoot":"","sources":["../../src/util/const.ts"],"names":[],"mappings":";;;AAOa,QAAA,mBAAmB,GAAG;IACjC,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,YAAY,EAAE,cAAc;IAC5B,SAAS,EAAE,WAAW;IACtB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;CACV,CAAC;AASE,QAAA,SAAS,GAAG;IACvB,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;CACV,CAAC;AASE,QAAA,UAAU,GAAG;IACxB,WAAW,EAAE,aAAa;IAC1B,KAAK,EAAE,OAAO;IACd,YAAY,EAAE,cAAc;IAC5B,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;CACV,CAAC;AASE,QAAA,uBAAuB,GAAG;IACrC,MAAM,EAAE,QAAQ;IAChB,GAAG,EAAE,KAAK;IACV,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,gBAAgB,EAAE,iBAAiB;IACnC,gBAAgB,EAAE,iBAAiB;IACnC,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;CACJ,CAAC;AASE,QAAA,yBAAyB,GAAG;IACvC,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;CACZ,CAAC;AASE,QAAA,aAAa,GAAG;IAC3B,GAAG,+BAAuB;IAC1B,GAAG,iCAAyB;CACpB,CAAC;AASE,QAAA,eAAe,GAAG;IAC7B,UAAU,EAAE,YAAY;IACxB,kBAAkB,EAAE,mBAAmB;CAC/B,CAAC;AASE,QAAA,mBAAmB,GAAG;IACjC,eAAe,EAAE,gBAAgB;IACjC,uBAAuB,EAAE,uBAAuB;CACxC,CAAC;AASE,QAAA,eAAe,GAAG;IAC7B,GAAG,2BAAmB;IACtB,GAAG,kBAAU;IACb,GAAG,qBAAa;IAChB,GAAG,uBAAe;IAClB,GAAG,2BAAmB;CACd,CAAC;AAeE,QAAA,QAAQ,GAAG;IACtB,GAAG,uBAAe;IAClB,GAAG,iBAAS;CACJ,CAAC"}

packages/types/src/Core/CoreObject.ts

@@ -8,19 +8,21 @@ import type {
   OrderedCollectionReference,
 } from '../Extended/Collection';
 
+/**
+ * A union of all Core Object types.
+ */
 export type AnyCoreObjectType =
   (typeof CoreObjectTypes)[keyof typeof CoreObjectTypes];
 
 /**
- * Objects are the core concept around which both ActivityStreams and ActivityPub
- * are built. Objects are often wrapped in Activities and are contained in streams
- * of Collections, which are themselves subclasses of Objects. See the
- * Activity-Vocabulary document, particularly the Core Classes; ActivityPub follows
- * the mapping of this vocabulary very closely.
+ * Properties common to all Core Objects.
  *
- * ActivityPub defines some terms in addition to those provided by ActivityStreams.
+ * @see https://www.w3.org/TR/activitystreams-core/#object
+ *
+ * @note The `sensitive` property is not included in the spec, but it is
+ * included because it is common to all ActivityPub objects in practice
+ * by way of an extension to the spec.
  */
-
 export type CoreObjectProperties = {
   // Activity Streams properties.
   attachment?: OrArray<EntityReference>;
@@ -35,11 +37,8 @@ export type CoreObjectProperties = {
   duration?: string;
   endTime?: Date;
   generator?: OrArray<EntityReference>;
-  icon?: ImageReference | LinkReference | Array<ImageReference | LinkReference>;
-  image?:
-    | ImageReference
-    | LinkReference
-    | Array<ImageReference | LinkReference>;
+  icon?: OrArray<ImageReference | LinkReference>;
+  image?: OrArray<ImageReference | LinkReference>;
   inReplyTo?: OrArray<EntityReference>;
   location?: OrArray<EntityReference>;
   mediaType?: string;

packages/types/src/Core/Entity.ts

@@ -1,5 +1,11 @@
 import { TypeOrArrayWithType, AnyType, OrArray } from '../util';
 
+/**
+ * A base ActivityStreams Entity is a plain object that has at least a `type`
+ * property.
+ *
+ * @todo Add better support for the `@context` property.
+ */
 export type BaseEntity<T extends AnyType> = {
   '@context'?: OrArray<URL | Record<string, URL>>;
   // Activity Pub allows null.

packages/types/src/Core/Link.ts

@@ -2,20 +2,14 @@ import { BaseEntity } from './Entity';
 import { LinkTypes, OrArray, StringReferenceMap } from '../util';
 import { EntityReference } from '.';
 
+/**
+ * A union of all Link types.
+ */
 export type AnyLinkType = (typeof LinkTypes)[keyof typeof LinkTypes];
 
 /**
- * Per the ActivityStreams Vocabulary spec:
- *
- * > A Link is an indirect, qualified reference to a resource identified by a URL.
- * > The fundamental model for links is established by [RFC5988]. Many of the
- * > properties defined by the Activity Vocabulary allow values that are either
- * > instances of Object or Link. When a Link is used, it establishes a qualified
- * > relation connecting the subject (the containing object) to the resource
- * > identified by the href. Properties of the Link are properties of the reference
- * > as opposed to properties of the resource.
+ * Properties common to all Link types.
  */
-
 export type LinkProperties = {
   height?: number;
   href?: URL;
@@ -28,10 +22,56 @@ export type LinkProperties = {
   width?: number;
 };
 
+/**
+ * The base type for all Link types.
+ *
+ * @note This differs from Link, which is the type for a Link entity
+ * specifically. This is the base type for all Link types, including the Link
+ * and Mention types.
+ *
+ * @extends BaseEntity
+ *
+ * @instance Link
+ * @instance Mention
+ */
 export type BaseLink<T extends AnyLinkType> = BaseEntity<T> & LinkProperties;
 
-type LinkEntity = BaseLink<typeof LinkTypes.LINK>;
+/**
+ * A Link entity.
+ *
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > A Link is an indirect, qualified reference to a resource identified by a
+ * > URL. The fundamental model for links is established by [RFC5988]. Many of
+ * > the properties defined by the Activity Vocabulary allow values that are
+ * > either instances of Object or Link. When a Link is used, it establishes a
+ * > qualified relation connecting the subject (the containing object) to the
+ * > resource identified by the href. Properties of the Link are properties of
+ * > the reference as opposed to properties of the resource.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-link
+ */
+export type LinkEntity = BaseLink<typeof LinkTypes.LINK>;
+
+/**
+ * A Mention entity.
+ *
+ * Per the ActivityPub spec:
+ *
+ * > A Mention is a specialization of Link that represents an @mention.
+ *
+ * @extends Link
+ *
+ * @see https://www.w3.org/TR/activitypub/#mention
+ */
 export type Mention = BaseLink<typeof LinkTypes.MENTION>;
 
+/**
+ * A Link entity or Mention entity.
+ */
 export type Link = LinkEntity | Mention;
+
+/**
+ * Either a Link or a URL reference to a Link.
+ */
 export type LinkReference = URL | Link;

packages/types/src/Core/index.ts

@@ -1,21 +1,56 @@
 import { Link, Mention } from './Link';
 import { Actor } from '../Extended/Actor';
 import { Activity } from '../Extended/Activity';
-import { Collection, OrderedCollection } from '../Extended/Collection';
-import { CollectionPage, OrderedCollectionPage } from '../Extended/Collection';
+import { AnyCollectionOrCollectionPage } from '../Extended/Collection';
 import { ExtendedObject } from '../Extended';
 export { CoreObjectProperties } from './CoreObject';
 export type { Link, LinkReference, Mention } from './Link';
 
+/**
+ * The base type for all ActivityPub Objects (including Extended Objects).
+ *
+ * @note This type is named `CoreObject` instead of `Object` because of the
+ * following concerns:
+ * - All ActivityPub Objects are objects, but not all objects are
+ *   ActivityPub Objects. In particular, Links are not ActivityPub Objects.
+ * - There are a set of Extended Objects that inherit from this type.
+ * - `Object` is a reserved keyword in JavaScript.
+ *
+ * @see https://www.w3.org/TR/activitystreams-core/#object
+ *
+ * @extends BaseEntity
+ *
+ * @instance ExtendedObject
+ * @instance Actor
+ * @instance Activity
+ * @instance Collection
+ */
 export type CoreObject =
   | ExtendedObject
   | Actor
   | Activity
-  | Collection
-  | OrderedCollection
-  | CollectionPage
-  | OrderedCollectionPage;
+  | AnyCollectionOrCollectionPage;
+
+/**
+ * Either a CoreObject or a URL reference to a CoreObject.
+ */
 export type CoreObjectReference = URL | CoreObject;
 
+/**
+ * The base type for all ActivityPub Entities, including Object and Link types.
+ *
+ * @note The spec does not specify a base type, but this library does for
+ * convenience and easier type checking.
+ *
+ * @note The spec allows the type to be optional, but it is required by this
+ * library in order to differentiate between different types of Entities.
+ *
+ * @instance CoreObject
+ * @instance Link
+ */
 export type Entity = CoreObject | Link | Mention;
+
+/**
+ * Either an Entity or a URL reference to an Entity.
+ */
 export type EntityReference = URL | Entity;

packages/types/src/Extended/Activity.ts

@@ -7,15 +7,27 @@ import {
 import { CoreObjectProperties, EntityReference } from '../Core';
 import { BaseEntity } from '../Core/Entity';
 
+/**
+ * A union of all Activity types.
+ */
 export type AnyActivityType =
   (typeof ActivityTypes)[keyof typeof ActivityTypes];
 
+/**
+ * A union of all Transitive Activity types.
+ */
 export type AnyTransitiveActivityType =
   (typeof TransitiveActivityTypes)[keyof typeof TransitiveActivityTypes];
 
+/**
+ * A union of all Intransitive Activity types.
+ */
 export type AnyIntransitiveActivityType =
   (typeof IntransitiveActivityTypes)[keyof typeof IntransitiveActivityTypes];
 
+/**
+ * Properties common to all Activity types.
+ */
 export type ActivityProperties = {
   actor: OrArray<EntityReference>;
   object?: OrArray<EntityReference>;
@@ -26,33 +38,50 @@ export type ActivityProperties = {
 };
 
 /**
- * Per the ActivityStreams Vocabulary spec:
+ * The base type for all Activity entities.
  *
- * > An Activity is a subtype of Object that describes some form of action that
- * > may happen, is currently happening, or has already happened. The Activity
- * > type itself serves as an abstract base type for all types of activities.
- * > It is important to note that the Activity type itself does not carry any
- * > specific semantics about the kind of action being taken.
+ * @extends CoreObject
  */
-
 type BaseActivity<T extends AnyActivityType> = BaseEntity<T> &
   CoreObjectProperties &
   ActivityProperties;
 
+/**
+ * Properties common to all TransitiveActivity types.
+ */
 type TransitiveActivityProperties = {
   object: OrArray<EntityReference>;
 };
 
-// Not part of the spec, but helpful in some situations.
+/**
+ * The base type for all TransitiveActivity entities, meaning those that have an
+ * `object` property.
+ *
+ * @note This is not in the spec, but it is useful for type checking.
+ *
+ * Inversing the definition of IntransitiveActivity from the ActivityStreams
+ * Vocabulary spec:
+ *
+ * > Instances of TransitiveActivity are a subtype of Activity representing
+ * > transitive actions. The object property is therefore required for these
+ * > activities.
+ *
+ * @extends Activity
+ */
 export type TransitiveActivity<T extends AnyTransitiveActivityType> =
   BaseActivity<T> & TransitiveActivityProperties;
 
 /**
+ * The base type for all IntransitiveActivity entities, meaning those that do
+ * not have an `object` property.
+ *
  * Per the ActivityStreams Vocabulary spec:
  *
  * > Instances of IntransitiveActivity are a subtype of Activity representing
  * > intransitive actions. The object property is therefore inappropriate for
  * > these activities.
+ *
+ * @extends Activity
  */
 export type IntransitiveActivity<T extends AnyIntransitiveActivityType> =
   BaseActivity<T>;
@@ -60,76 +89,415 @@ export type IntransitiveActivity<T extends AnyIntransitiveActivityType> =
 /**
  * Per the ActivityStreams Vocabulary spec:
  *
- * All Activity Types inherit the properties of the base Activity type.
- * Some specific Activity Types are subtypes or specializations of more
- * generalized Activity Types (for instance, the Invite Activity Type
- * is a more specific form of the Offer Activity Type).
+ * > Indicates that the actor has accepted the object. The target property can
+ * > be used in certain circumstances to indicate the context into which the
+ * > object has been accepted.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-accept
+ *
+ * @type TransitiveActivity
  */
-
 export type Accept = TransitiveActivity<typeof ActivityTypes.ACCEPT>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor is tentatively accepting the object. The target
+ * > property can be used in certain circumstances to indicate the context into
+ * > which the object has been accepted.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-tentative-accept
+ *
+ * @type TransitiveActivity
+ */
 export type TentativeAccept = TransitiveActivity<
   typeof ActivityTypes.TENTATIVE_ACCEPT
 >;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor has added the object to the target. If the target
+ * > property is not explicitly specified, the target would need to be
+ * > determined implicitly by context. The origin can be used to identify the
+ * > context from which the object originated.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-add
+ *
+ * @type TransitiveActivity
+ */
 export type Add = TransitiveActivity<typeof ActivityTypes.ADD>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor has arrived at the location. The origin can be
+ * > used to identify the context from which the actor originated. The target
+ * > typically has no defined meaning.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-arrive
+ *
+ * @type IntransitiveActivity
+ */
 export type Arrive = IntransitiveActivity<typeof ActivityTypes.ARRIVE>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor has created the object.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-create
+ *
+ * @type TransitiveActivity
+ */
 export type Create = TransitiveActivity<typeof ActivityTypes.CREATE>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor has deleted the object. If specified, the origin
+ * > indicates the context from which the object was deleted.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-delete
+ *
+ * @type TransitiveActivity
+ */
 export type Delete = TransitiveActivity<typeof ActivityTypes.DELETE>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor is "following" the object. Following is defined in
+ * > the sense typically used within Social systems in which the actor is
+ * > interested in any activity performed by or on the object. The target and
+ * > origin typically have no defined meaning.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-follow
+ *
+ * @type TransitiveActivity
+ */
 export type Follow = TransitiveActivity<typeof ActivityTypes.FOLLOW>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor is ignoring the object. The target and origin
+ * > typically have no defined meaning.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-ignore
+ */
 export type Ignore = TransitiveActivity<typeof ActivityTypes.IGNORE>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor has joined the object. The target and origin
+ * > typically have no defined meaning.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-join
+ *
+ * @type TransitiveActivity
+ */
 export type Join = TransitiveActivity<typeof ActivityTypes.JOIN>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor is leaving the object. If specified, the origin
+ * > indicates the context from which the actor is leaving.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-leave
+ *
+ * @type TransitiveActivity
+ */
 export type Leave = TransitiveActivity<typeof ActivityTypes.LEAVE>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor likes, recommends or endorses the object. The
+ * > target and origin typically have no defined meaning.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-like
+ *
+ * @type TransitiveActivity
+ */
 export type Like = TransitiveActivity<typeof ActivityTypes.LIKE>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor is offering the object. If specified, the target
+ * > indicates the entity to which the object is being offered.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-offer
+ *
+ * @type TransitiveActivity
+ */
 export type Offer = TransitiveActivity<typeof ActivityTypes.OFFER>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor is inviting the object to target. If the origin
+ * > property is not specified, the target is notified directly. For instance,
+ * > Alice can invite Joe to an event by posting an Invite object to her
+ * > personal stream or by mentioning him, effectively inviting him to the
+ * > event.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-invite
+ *
+ * @type TransitiveActivity
+ */
 export type Invite = TransitiveActivity<typeof ActivityTypes.INVITE>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor is rejecting the object. The target and origin
+ * > typically have no defined meaning.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-reject
+ *
+ * @type TransitiveActivity
+ */
 export type Reject = TransitiveActivity<typeof ActivityTypes.REJECT>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor is tentatively rejecting the object. The target
+ * > and origin typically have no defined meaning.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-tentative-reject
+ *
+ * @type TransitiveActivity
+ */
 export type TentativeReject = TransitiveActivity<
   typeof ActivityTypes.TENTATIVE_REJECT
 >;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor has removed the object. If specified, the origin
+ * > indicates the context from which the object was removed.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-remove
+ *
+ * @type TransitiveActivity
+ */
 export type Remove = TransitiveActivity<typeof ActivityTypes.REMOVE>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor is undoing the object. In most cases, the object
+ * > will be an Activity describing some previously performed action (for
+ * > instance, a person may have previously "liked" an article but, for whatever
+ * > reason, might choose to undo that like at some later point in time).
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-undo
+ *
+ * @type TransitiveActivity
+ */
 export type Undo = TransitiveActivity<typeof ActivityTypes.UNDO>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor has updated the object. Note, however, that this
+ * > vocabulary does not define a mechanism for describing the actual set of
+ * > modifications made to object. The target and origin typically have no
+ * > defined meaning.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-update
+ *
+ * @type TransitiveActivity
+ */
 export type Update = TransitiveActivity<typeof ActivityTypes.UPDATE>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor has viewed the object.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-view
+ *
+ * @type TransitiveActivity
+ */
 export type View = TransitiveActivity<typeof ActivityTypes.VIEW>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor has listened to the object.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-listen
+ *
+ * @type TransitiveActivity
+ */
 export type Listen = TransitiveActivity<typeof ActivityTypes.LISTEN>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor has read the object.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-read
+ *
+ * @type TransitiveActivity
+ */
 export type Read = TransitiveActivity<typeof ActivityTypes.READ>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor has moved object from origin to target. If the
+ * > origin or target are not specified, either can be determined by context.
+ * > The origin SHOULD NOT be used to express hierarchical or containment
+ * > relationships. For example, when moving an object from one folder to
+ * > another, leave origin out (instead of making the origin the containing
+ * > folder).
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-move
+ *
+ * @type TransitiveActivity
+ */
 export type Move = TransitiveActivity<typeof ActivityTypes.MOVE>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor is traveling to target from origin. Travel is an
+ * > IntransitiveObject whose actor specifies the direct object. If the target
+ * > or origin are not specified, either can be determined by context. Travel
+ * > indicates that the actor is moving to the target from the origin. The
+ * > duration and distance properties can be used to indicate the time or
+ * > distance of the travel, but they are not necessary. If a matching
+ * > IntransitiveActivity object exists, then the Travel object is considered an
+ * > alternate view of the same activity.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-travel
+ *
+ * @type IntransitiveActivity
+ */
 export type Travel = IntransitiveActivity<typeof ActivityTypes.TRAVEL>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor has announced an object to the target. The
+ * > origin typically has no defined meaning.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-announce
+ *
+ * @type TransitiveActivity
+ */
 export type Announce = TransitiveActivity<typeof ActivityTypes.ANNOUNCE>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor is blocking the object. Blocking is a stronger
+ * > form of Ignore. The typical use is to support social systems that allow
+ * > one user to block activities or content of other users. The target and
+ * > origin typically have no defined meaning.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-block
+ *
+ * @type TransitiveActivity
+ */
 export type Block = TransitiveActivity<typeof ActivityTypes.BLOCK>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor is "flagging" the object. Flagging is defined in
+ * > the sense common to many social platforms as reporting content as being
+ * > inappropriate for any number of reasons.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-flag
+ *
+ * @type TransitiveActivity
+ */
 export type Flag = TransitiveActivity<typeof ActivityTypes.FLAG>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > Indicates that the actor dislikes the object. The target and origin
+ * > typically have no defined meaning.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-dislike
+ *
+ * @type TransitiveActivity
+ */
 export type Dislike = TransitiveActivity<typeof ActivityTypes.DISLIKE>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > A Question is an IntransitiveActivity that indicates that the actor is
+ * > asking the target a question. Question objects are an extension of
+ * > IntransitiveActivity. That is, the Question object is an Activity, but the
+ * > direct object is the question itself and therefore it would not contain an
+ * > object property. Either of the anyOf and oneOf properties MAY be used to
+ * > express possible answers, but a Question object MUST NOT have both
+ * > properties.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-question
+ *
+ * @type IntransitiveActivity
+ */
 export type Question = IntransitiveActivity<typeof ActivityTypes.QUESTION> & {
   oneOf: OrArray<EntityReference>;
   anyOf: OrArray<EntityReference>;
   closed: EntityReference | Date | boolean;
 };
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > An Activity is a subtype of Object that describes some form of action that
+ * > may happen, is currently happening, or has already happened. The Activity
+ * > type itself serves as an abstract base type for all types of activities.
+ * > It is important to note that the Activity type itself does not carry any
+ * > specific semantics about the kind of action being taken.
+ *
+ * @see https://www.w3.org/TR/activitystreams-core/#activities
+ *
+ * @extends CoreObject
+ *
+ * @instance Accept
+ * @instance TentativeAccept
+ * @instance Add
+ * @instance Arrive
+ * @instance Create
+ * @instance Delete
+ * @instance Follow
+ * @instance Ignore
+ * @instance Join
+ * @instance Leave
+ * @instance Like
+ * @instance Offer
+ * @instance Invite
+ * @instance Reject
+ * @instance TentativeReject
+ * @instance Remove
+ * @instance Undo
+ * @instance Update
+ * @instance View
+ * @instance Listen
+ * @instance Read
+ * @instance Move
+ * @instance Travel
+ * @instance Announce
+ * @instance Block
+ * @instance Flag
+ * @instance Dislike
+ * @instance Question
+ */
 export type Activity =
   | Accept
   | Follow
@@ -160,4 +528,7 @@ export type Activity =
   | Dislike
   | Question;
 
+/**
+ * Either an Activity or a URL reference to an Activity.
+ */
 export type ActivityReference = URL | Activity;

packages/types/src/Extended/Actor.ts

@@ -8,10 +8,21 @@ import {
 } from './Collection';
 import { StringReferenceMap } from '../util';
 
+/**
+ * A union of all Actor types.
+ */
 export type AnyActorType = (typeof ActorTypes)[keyof typeof ActorTypes];
 
+/**
+ * Properties common to all Actor types.
+ *
+ * @see https://www.w3.org/TR/activitypub/#actors
+ *
+ * @note The `manuallyApprovesFollowers` property is not included in the spec,
+ * but it is included because it is common to all ActivityPub objects in
+ * practice by way of an extension to the spec.
+ */
 export type ActorProperties = {
-  // Activity Pub properties.
   inbox: OrderedCollectionReference;
   outbox: OrderedCollectionReference;
   following?: CollectionReference;
@@ -38,30 +49,83 @@ export type ActorProperties = {
 };
 
 /**
- * In ActivityPub, a user is represented by "actors" via the user's accounts
- * on servers. User's accounts on different servers correspond to different actors.
+ * The base type for all Actor entities.
  *
- * Every Actor has:
- * An inbox: How they get messages from the world
- * An outbox: How they send messages to others
+ * @extends BaseEntity
  *
- * These are endpoints, or really, just URLs which are listed in the ActivityPub
- * actor's ActivityStreams description.
+ * @instance Application
+ * @instance Group
+ * @instance Organization
+ * @instance Person
+ * @instance Service
  */
-
 type BaseActor<T extends AnyActorType> = BaseEntity<T> &
   CoreObjectProperties &
   ActorProperties;
 
+/**
+ * Per the ActivitySteams spec:
+ *
+ * > Describes a software application.
+ *
+ * @type Actor
+ */
 export type Application = BaseActor<typeof ActorTypes.APPLICATION>;
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > Represents an individual person.
+ *
+ * @type Actor
+ */
 export type Person = BaseActor<typeof ActorTypes.PERSON>;
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > Represents a formal or informal collective of Actors.
+ *
+ * @type Actor
+ */
 export type Group = BaseActor<typeof ActorTypes.GROUP>;
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > Represents a service of any kind.
+ *
+ * @type Actor
+ */
 export type Service = BaseActor<typeof ActorTypes.SERVICE>;
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > Represents an organization.
+ *
+ * @type Actor
+ */
 export type Organization = BaseActor<typeof ActorTypes.ORGANIZATION>;
 
+/**
+ * Per the ActivityStreams Vocabulary spec:
+ *
+ * > An Entity that either performed or is expected to perform an Activity.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-actor
+ *
+ * @extends CoreObject
+ *
+ * @instance Application
+ * @instance Group
+ * @instance Organization
+ * @instance Person
+ * @instance Service
+ */
 export type Actor = Application | Service | Group | Organization | Person;
+
+/**
+ * Either an Actor or a URL reference to an Actor.
+ */
 export type ActorReference = URL | Actor;

packages/types/src/Extended/Collection.ts

@@ -4,65 +4,219 @@ import { EntityReference } from '../Core';
 import { Link } from '../Core/Link';
 import { BaseEntity } from '../Core/Entity';
 
+/** A union of all Collection types. */
 export type AnyCollectionType =
   (typeof CollectionTypes)[keyof typeof CollectionTypes];
 
+/** A union of all CollectionPage types. */
 export type AnyCollectionPageType =
   (typeof CollectionPageTypes)[keyof typeof CollectionPageTypes];
 
+/**
+ * A union of all Collection and CollectionPage types.
+ */
 export type AnyCollectionOrCollectionPageType =
   | AnyCollectionType
   | AnyCollectionPageType;
 
+/**
+ * Properties common to all Collection types.
+ */
 type CollectionProperties = {
   totalItems?: number;
   items?: OrArray<EntityReference>;
+  startIndex?: number;
   orderedItems?: OrArray<EntityReference>;
   current?: URL | CollectionPage | Link;
   first?: URL | CollectionPage | Link;
   last?: URL | CollectionPage | Link;
 };
 
+/**
+ * The base type for all Collection and CollectionPage entities.
+ *
+ * Per the ActivityPub spec:
+ *
+ * > A Collection is a subtype of Object that represents ordered or unordered
+ * > sets of Object or Link instances.
+ *
+ * Per the Activity Streams 2.0 Core spec:
+ *
+ * > Collection objects are a specialization of the base Object that serve as a
+ * > container for other Objects or Links.
+ *
+ * @extends BaseEntity
+ * @extends CoreObjectProperties
+ * @extends CollectionProperties
+ *
+ * @instance Collection
+ * @instance OrderedCollection
+ * @instance CollectionPage
+ * @instance OrderedCollectionPage
+ *
+ * @see https://www.w3.org/TR/activitypub/#collection
+ */
 export type BaseCollection<T extends AnyCollectionOrCollectionPageType> =
   BaseEntity<T> & CoreObjectProperties & CollectionProperties;
 
+/**
+ * This type indicates a Collection object with a type of `Collection`.
+ *
+ * @note Although use of "orderedItems" with "Collection" is not prohibited by
+ * the spec, it is not recommended. Use "OrderedCollection" instead.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-collection
+ *
+ * @type Collection
+ */
 export type Collection = BaseCollection<typeof CollectionTypes.COLLECTION>;
 
+/**
+ * This type indicates a Collection object with a type of `OrderedCollection`.
+ *
+ * @note Although use of "items" with "OrderedCollection" is not prohibited by
+ * the spec, it is not recommended. Use "Collection" instead.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-orderedcollection
+ *
+ * @extends Collection
+ */
 export type OrderedCollection = BaseCollection<
   typeof CollectionTypes.ORDERED_COLLECTION
 >;
 
+/**
+ * Properties common to all CollectionPage types.
+ */
 type CollectionPageProperties = {
   partOf?: URL | EitherCollection | Link;
   next?: URL | CollectionPage | Link;
   prev?: URL | CollectionPage | Link;
 };
 
+/**
+ * The base type for all CollectionPage entities.
+ *
+ * @extends Collection
+ *
+ * @instance CollectionPage
+ * @instance OrderedCollectionPage
+ */
 type BaseCollectionPage<T extends AnyCollectionPageType> = BaseCollection<T> &
   CollectionPageProperties;
 
+/**
+ * This type indicates a CollectionPage object with a type of `CollectionPage`.
+ *
+ * Per the ActivityStreams 2.0 Core spec:
+ *
+ * > A CollectionPage is a subtype of Collection that represents a subset of
+ * > items from another Collection. CollectionPage instances are typically
+ * > used to represent the items on a single page of a multi-page
+ * > Collection. They typically have a shorter lifespan than the Collection
+ * > instances that contain them. While a Collection indicates the entire
+ * > set of items a CollectionPage MAY be used to represent a subset of
+ * > those items. For example, an Activity MAY be associated with a
+ * > Collection of likes. The Collection might represent all of the likes
+ * > that the activity has received. A CollectionPage with a `partOf`
+ * > property of the Activity MAY be used to represent a subset of those
+ * > likes from a single page.
+ *
+ * @extends Collection
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-collectionpage
+ * @see https://www.w3.org/TR/activitystreams-core/#collectionpage
+ * @see https://www.w3.org/TR/activitypub/#collectionpage
+ */
 export type CollectionPage = BaseCollectionPage<
   typeof CollectionPageTypes.COLLECTION_PAGE
 >;
 
-type OrderedCollectionPageProperties = {
-  startIndex?: number;
-  orderedItems?: OrArray<EntityReference>;
-};
-
+/**
+ * This type indicates a CollectionPage object with a type of
+ * `OrderedCollectionPage`.
+ *
+ * Per the ActivityPub spec:
+ *
+ * > Used to represent ordered subsets of items from an OrderedCollection.
+ *
+ * This is typically used to represent pages of items in a collection that
+ * maintain a specific order.
+ *
+ * @extends CollectionPage
+ *
+ * @see CollectionPage
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-orderedcollectionpage
+ * @see https://www.w3.org/TR/activitystreams-core/#orderedcollectionpage
+ * @see https://www.w3.org/TR/activitypub/#orderedcollectionpage
+ */
 export type OrderedCollectionPage = BaseCollectionPage<
   typeof CollectionPageTypes.ORDERED_COLLECTION_PAGE
-> &
-  OrderedCollectionPageProperties;
+>;
 
+/**
+ * A reference to a Collection object or a URL reference to a Collection object.
+ */
 export type CollectionReference = URL | Collection;
+
+/**
+ * A reference to an OrderedCollection object or a URL reference to an
+ * OrderedCollection object.
+ */
 export type OrderedCollectionReference = URL | OrderedCollection;
 
+/**
+ * A reference to a CollectionPage object or a URL reference to a CollectionPage
+ * object.
+ */
 export type CollectionPageReference = URL | CollectionPage;
+
+/**
+ * A reference to an OrderedCollectionPage object or a URL reference to an
+ * OrderedCollectionPage object.
+ */
 export type OrderedCollectionPageReference = URL | OrderedCollectionPage;
 
+/**
+ * Either a Collection or OrderedCollection object.
+ */
 export type EitherCollection = Collection | OrderedCollection;
+
+/**
+ * Either a CollectionPage or OrderedCollectionPage object or a URL reference to
+ * a CollectionPage or OrderedCollectionPage object.
+ */
 export type EitherCollectionPage = CollectionPage | OrderedCollectionPage;
 
+/**
+ * A reference to a Collection or OrderedCollection object or a URL reference to
+ * a Collection or OrderedCollection object.
+ */
 export type EitherCollectionReference = URL | EitherCollection;
+
+/**
+ * A reference to a CollectionPage or OrderedCollectionPage object or a URL
+ * reference to a CollectionPage or OrderedCollectionPage object.
+ */
 export type EitherCollectionPageReference = URL | EitherCollectionPage;
+
+/**
+ * Any among a Collection, OrderedCollection, CollectionPage, or
+ * OrderedCollectionPage object.
+ *
+ * @note This is useful for functions that accept any type that descends
+ * from BaseCollection.
+ */
+export type AnyCollectionOrCollectionPage =
+  | EitherCollection
+  | EitherCollectionPage;
+
+/**
+ * Any among a Collection, OrderedCollection, CollectionPage, or
+ * OrderedCollectionPage object or a URL reference to a Collection,
+ * OrderedCollection, CollectionPage, or OrderedCollectionPage object.
+ */
+export type AnyCollectionOrCollectionPageReference =
+  | URL
+  | AnyCollectionOrCollectionPage;

packages/types/src/Extended/ExtendedObject.ts

@@ -8,12 +8,48 @@ import { CoreObjectProperties } from '../Core/CoreObject';
 import { EntityReference, CoreObjectReference } from '../Core';
 import { BaseEntity } from '../Core/Entity';
 
+/**
+ * A union of all Extended Object types.
+ */
 export type AnyExtendedObjectType =
   (typeof ExtendedObjectTypes)[keyof typeof ExtendedObjectTypes];
 
+/**
+ * The base type for all Extended Object entities.
+ *
+ * @extends BaseEntity
+ * @extends CoreObjectProperties
+ *
+ * @instance Article
+ * @instance Event
+ * @instance Note
+ * @instance Page
+ * @instance Place
+ * @instance Relationship
+ * @instance Tombstone
+ * @instance Profile
+ * @instance Video
+ * @instance Document
+ * @instance Audio
+ * @instance Image
+ * @instance Hashtag
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#extended-types
+ */
 export type BaseExtendedObject<T extends AnyExtendedObjectType> =
   BaseEntity<T> & CoreObjectProperties;
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > A Tombstone is a special kind of Object that represents a content object
+ * > that has been deleted. It can be used in Collections to signify that there
+ * > used to be an object at this position, but it has been deleted.
+ *
+ * @type ExtendedObject
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-tombstone
+ */
 export type Tombstone = BaseExtendedObject<
   typeof ExtendedObjectTypes.TOMBSTONE
 > & {
@@ -21,6 +57,17 @@ export type Tombstone = BaseExtendedObject<
   deleted?: Date;
 };
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > A Relationship is an indirect Entity that describes a relationship between
+ * > two individuals. The subject and object properties are used to identify the
+ * > connected individuals.
+ *
+ * @type ExtendedObject
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-relationship
+ */
 export type Relationship = BaseExtendedObject<
   typeof ExtendedObjectTypes.RELATIONSHIP
 > & {
@@ -29,14 +76,77 @@ export type Relationship = BaseExtendedObject<
   relationship?: CoreObjectReference;
 };
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > A Profile is a content object that describes another Object, typically used
+ * > to describe Actor Type objects. The describes property is used to reference
+ * > the object being described by the profile.
+ *
+ * @type ExtendedObject
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-profile
+ */
 export type Article = BaseExtendedObject<typeof ExtendedObjectTypes.ARTICLE>;
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > Represents a short written work typically less than a single paragraph in
+ * > length.
+ *
+ * @type ExtendedObject
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-note
+ */
 export type Note = BaseExtendedObject<typeof ExtendedObjectTypes.NOTE>;
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > Represents a Web Page.
+ *
+ * @type ExtendedObject
+ *
+ * @note Technically this extends Document, but Document has no special
+ * properties.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-page
+ */
 export type Page = BaseExtendedObject<typeof ExtendedObjectTypes.PAGE>;
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > Represents any kind of event.
+ *
+ * @type ExtendedObject
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-event
+ */
 export type Event = BaseExtendedObject<typeof ExtendedObjectTypes.EVENT>;
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > Represents a logical or physical location.
+ *
+ * Additionally, per the spec:
+ *
+ * > The Place object is used to represent both physical and logical locations.
+ * > While numerous existing vocabularies exist for describing locations in a
+ * > variety of ways, inconsistencies and incompatibilities between those
+ * > vocabularies make it difficult to achieve appropriate interoperability
+ * > between implementations. The Place object is included within the Activity
+ * > vocabulary to provide a minimal, interoperable starting point for
+ * > describing locations consistently across Activity Streams 2.0
+ * > implementations.
+ *
+ * @type ExtendedObject
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-place
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#places
+ */
 export type Place = BaseExtendedObject<typeof ExtendedObjectTypes.PLACE> & {
   accuracy?: number;
   altitude?: number;
@@ -46,21 +156,98 @@ export type Place = BaseExtendedObject<typeof ExtendedObjectTypes.PLACE> & {
   units?: string;
 };
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > A Document is a content object that represents another resource, typically
+ * > used to describe things that are capable of being embedded or attached to
+ * > other content.
+ *
+ * @type ExtendedObject
+ *
+ * @note Technically several other types extend Document, but Document has no
+ * special properties. The types include: Image, Audio, Video, and Profile.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-document
+ */
 export type Document = BaseExtendedObject<typeof ExtendedObjectTypes.DOCUMENT>;
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > An image document of any kind.
+ *
+ * @type ExtendedObject
+ *
+ * @note Technically this extends Document, but Document has no special
+ * properties.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-image
+ */
 export type Image = BaseExtendedObject<typeof ExtendedObjectTypes.IMAGE>;
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > Represents an audio document of any kind.
+ *
+ * @type ExtendedObject
+ *
+ * @note Technically this extends Document, but Document has no special
+ * properties.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-audio
+ */
 export type Audio = BaseExtendedObject<typeof ExtendedObjectTypes.AUDIO>;
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > Represents a video document of any kind.
+ *
+ * @type ExtendedObject
+ *
+ * @note Technically this extends Document, but Document has no special
+ * properties.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-video
+ */
 export type Video = BaseExtendedObject<typeof ExtendedObjectTypes.VIDEO>;
 
+/**
+ * Per the ActivityStreams spec:
+ *
+ * > A Profile is a content object that describes another Object, typically used
+ * > to describe Actor Type objects. The describes property is used to reference
+ * > the object being described by the profile.
+ *
+ * @type ExtendedObject
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-profile
+ */
 export type Profile = BaseExtendedObject<typeof ExtendedObjectTypes.PROFILE> & {
   describes?: CoreObjectReference;
 };
 
-// Extension
+/**
+ * A Hashtag.
+ *
+ * @type ExtendedObject
+ *
+ * @note This is not part of the ActivityPub spec, but it is common in practice
+ * by way of extensions to the spec.
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-hashtag
+ */
 export type Hashtag = BaseExtendedObject<typeof ExtendedObjectTypes.HASHTAG>;
 
+/**
+ * A union of all Extended Object types.
+ *
+ * @extends CoreObject
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#extendedtypes
+ */
 export type ExtendedObject =
   | Article
   | Event
@@ -75,5 +262,13 @@ export type ExtendedObject =
   | Audio
   | Image
   | Hashtag;
+
+/**
+ * An Extended Object or a URL reference to an Extended Object.
+ */
 export type ExtendedObjectReference = URL | ExtendedObject;
+
+/**
+ * An Image or a URL reference to an Image.
+ */
 export type ImageReference = URL | Image;

packages/types/src/util/const.ts

@@ -1,3 +1,10 @@
+/**
+ * An object containing all the types of ExtendedObjects.
+ *
+ * @see ExtendedObject
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#extendedtypes
+ */
 export const ExtendedObjectTypes = {
   ARTICLE: 'Article',
   AUDIO: 'Audio',
@@ -14,11 +21,25 @@ export const ExtendedObjectTypes = {
   HASHTAG: 'Hashtag', // Extension
 } as const;
 
+/**
+ * An object containing all the types of Links.
+ *
+ * @see Link
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#links
+ */
 export const LinkTypes = {
   LINK: 'Link',
   MENTION: 'Mention',
 } as const;
 
+/**
+ * An object containing all the types of Actors.
+ *
+ * @see Actor
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#actors
+ */
 export const ActorTypes = {
   APPLICATION: 'Application',
   GROUP: 'Group',
@@ -27,6 +48,13 @@ export const ActorTypes = {
   SERVICE: 'Service',
 } as const;
 
+/**
+ * An object containing all the types of Transitive Activities.
+ *
+ * @see TransitiveActivity
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#transitive-activity-types
+ */
 export const TransitiveActivityTypes = {
   ACCEPT: 'Accept',
   ADD: 'Add',
@@ -55,27 +83,62 @@ export const TransitiveActivityTypes = {
   VIEW: 'View',
 } as const;
 
+/**
+ * An object containing all the types of Intransitive Activities.
+ *
+ * @see IntransitiveActivity
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#intransitive-activity-types
+ */
 export const IntransitiveActivityTypes = {
   ARRIVE: 'Arrive',
   TRAVEL: 'Travel',
   QUESTION: 'Question',
 } as const;
 
+/**
+ * An object containing all the types of Activities.
+ *
+ * @see Activity
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#activity-types
+ */
 export const ActivityTypes = {
   ...TransitiveActivityTypes,
   ...IntransitiveActivityTypes,
 } as const;
 
+/**
+ * An object containing all the types of Collections.
+ *
+ * @see Collection
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-collection
+ */
 export const CollectionTypes = {
   COLLECTION: 'Collection',
   ORDERED_COLLECTION: 'OrderedCollection',
 } as const;
 
+/**
+ * An object containing all the types of CollectionPages.
+ *
+ * @see CollectionPage
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-collectionpage
+ */
 export const CollectionPageTypes = {
   COLLECTION_PAGE: 'CollectionPage',
   ORDERED_COLLECTION_PAGE: 'OrderedCollectionPage',
 } as const;
 
+/**
+ * An object containing all the types of CoreObjects.
+ *
+ * @see CoreObject
+ *
+ * @see https://www.w3.org/TR/activitystreams-core/#object
+ */
 export const CoreObjectTypes = {
   ...ExtendedObjectTypes,
   ...ActorTypes,
@@ -84,11 +147,53 @@ export const CoreObjectTypes = {
   ...CollectionPageTypes,
 } as const;
 
+/**
+ * All the types of Entities.
+ *
+ * @see Entity
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-object
+ * @see https://www.w3.org/TR/activitypub/#object
+ * @see https://www.w3.org/TR/activitystreams-core/#object
+ *
+ * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-link
+ * @see https://www.w3.org/TR/activitypub/#link
+ * @see https://www.w3.org/TR/activitystreams-core/#link
+ */
 export const AllTypes = {
   ...CoreObjectTypes,
   ...LinkTypes,
 } as const;
 
+/**
+ * A union of all Entity types.
+ */
 export type AnyType = (typeof AllTypes)[keyof typeof AllTypes];
 
+/**
+ * A type alias representing the provided ActivityPub type or an array of
+ * ActivityPub types which includes the provided type.
+ *
+ * @param T The type to be used. The type must be a valid ActivityPub type.
+ *
+ * @example
+ * ```ts
+ * // A single type.
+ * const a: TypeOrArrayWithType<'Article'> = 'Article';
+ *
+ * // An array of types.
+ * const b: TypeOrArrayWithType<'Article'> = ['Article', 'Note'];
+ * ```
+ *
+ * @note This type is used to represent the `type` property of an ActivityPub
+ * object. The `type` property can be a single type or an array of types.
+ *
+ * @note Having multiple types in the `type` property is permitted in JSON-LD,
+ * however some ActivityPub implementations may not support it. For this reason,
+ * it is recommended to only use a single type. Internally, the first type in
+ * the array will be used as the primary type.
+ *
+ * @note Additional non-ActivityPub types may be included in the array, but
+ * they will not be validated.
+ */
 export type TypeOrArrayWithType<T extends AnyType> = T | [T, ...Array<AnyType>];

packages/types/src/util/values.ts

@@ -1,2 +1,23 @@
+/**
+ * Shorthand for a plain object with string keys and string values.
+ */
 export type StringReferenceMap = Record<string, string>;
+
+/**
+ * Shorthand for a value of a given type or array of values that all conform
+ * to that type.
+ *
+ * This is useful internally to represent many ActivityPub properties.
+ *
+ * @param T The type of the value to be mapped.
+ *
+ * @example
+ * ```ts
+ * // A string or array of strings.
+ * type StringOrArrayOfStrings = OrArray<string>;
+ *
+ * const a: StringOrArrayOfStrings = 'foo';
+ * const b: StringOrArrayOfStrings = ['foo', 'bar'];
+ * ```
+ */
 export type OrArray<T> = T | T[];

packages/utilities/src/compressEntity.ts

@@ -10,6 +10,11 @@ export function compressEntity(entity: AP.Entity): AP.Entity | null {
   return cast.isApEntity(compressObject(entity)) ?? null;
 }
 
+/**
+ * Compresses an object by replacing all nested Entities with their URLs.
+ *
+ * @returns The compressed object.
+ */
 function compressObject(
   object: Record<string, unknown>,
 ): Record<string, unknown> {
@@ -22,6 +27,12 @@ function compressObject(
   return compressed;
 }
 
+/**
+ * Compresses an unknown value by replacing all nested Entities with their
+ * URLs.
+ *
+ * @returns The compressed value.
+ */
 function compressUnknown(item: unknown): unknown {
   if (!guard.exists(item)) {
     return item;

packages/utilities/src/convertEntityToJson.ts

@@ -12,6 +12,11 @@ export function convertEntityToJson(
   return cast.isPlainObject(convertObject(object)) ?? {};
 }
 
+/**
+ * Converts an object to a plain JSON object.
+ *
+ * @returns The plain object.
+ */
 function convertObject(
   object: Record<string, unknown>,
 ): Record<string, unknown> {
@@ -24,6 +29,11 @@ function convertObject(
   return converted;
 }
 
+/**
+ * Converts an unknown value to a plain JSON value.
+ *
+ * @returns The plain value.
+ */
 function convertUnknown(value: unknown): unknown {
   if (!guard.exists(value)) {
     return value;

packages/utilities/src/convertJsonLdToEntity.ts

@@ -31,6 +31,16 @@ export async function convertJsonLdToEntity(
   return applyContext(converted);
 }
 
+/**
+ * Custom document loader for JSON-LD that uses cached contexts.
+ *
+ * Bundling the contexts saves on the number of requests made when parsing
+ * received JSON-LD documents.
+ *
+ * Based on the JSON-LD library's node document loader.
+ *
+ * @returns The remote JSON-LD document.
+ */
 async function customLoader(
   url: string,
   callback: (err: Error, remoteDoc: RemoteDocument) => void,

packages/utilities/src/convertJsonToEntity.ts

@@ -3,7 +3,7 @@ import { cast, guard } from '@activity-kit/type-utilities';
 import { PUBLIC_ACTOR } from './globals';
 
 /**
- * Converts a JSON object to an Entity.
+ * Converts a JSON object to an Entity with deserialized values.
  *
  * @returns The Entity, or null if not an Entity.
  */
@@ -13,6 +13,11 @@ export function convertJsonToEntity(
   return cast.isApEntity(convertObject(object)) ?? null;
 }
 
+/**
+ * Deserializes serialized values in an object into their proper types.
+ *
+ * @returns The object with deserialized values.
+ */
 function convertObject(
   object: Record<string, unknown>,
 ): Record<string, unknown> {
@@ -25,6 +30,11 @@ function convertObject(
   return converted;
 }
 
+/**
+ * Deserializes an unknown value into a known type.
+ *
+ * @returns The deserialized value.
+ */
 function convertUnknown(value: unknown): unknown {
   if (!guard.exists(value)) {
     return value;

packages/utilities/src/deduplicateUrls.ts

@@ -1,5 +1,7 @@
 /**
  * Removes duplicate URLs from an array of URLs.
+ *
+ * @returns An array of unique URLs.
  */
 export const deduplicateUrls = (unfilteredUrls: URL[]) => {
   return [...new Set(unfilteredUrls.map((url) => url.toString()))].map(

packages/utilities/src/getCollectionNameByUrl.ts

@@ -3,6 +3,11 @@ import { LOCAL_HOSTNAME } from './globals';
 /**
  * Gets the database collection name for a given URL.
  *
+ * Currently, all entities are stored in one of two collections:
+ *
+ * - `entity` for local entities
+ * - `foreignEntity` for foreign/remote entities
+ *
  * @returns The collection name.
  */
 export const getCollectionNameByUrl = (url: URL) => {

packages/utilities/src/getId.ts

@@ -2,12 +2,12 @@ import * as AP from '@activity-kit/types';
 import { guard } from '@activity-kit/type-utilities';
 
 /**
- * Get the URL from an EntityReference, if the EntityReference is a URL.
+ * Get the URL from an EntityReference.
  *
  * @returns The URL, or null if not a URL.
  */
 export const getId = (
-  entity?: undefined | null | AP.EntityReference | AP.EntityReference[],
+  entity: undefined | null | AP.EntityReference | AP.EntityReference[],
 ): URL | null => {
   if (!guard.exists(entity)) {
     return null;

packages/utilities/types/jsonldDocumentLoader.d.ts

@@ -1,3 +1,7 @@
+/**
+ * This file is used to declare the jsonldDocumentLoader module used in
+ * convertJsonLdToEntity.ts.
+ */
 declare module 'jsonld/lib/documentLoaders/node' {
   import * as jsonld from 'jsonld';
   export default function (): jsonld.Options.DocLoader['documentLoader'];