Unverified Commit 3633f763 authored by Hong Minhee's avatar Hong Minhee
Browse files

Utilities for traversing remote collections 

Close https://github.com/dahlia/fedify/issues/150
parent a021870e

.vscode/settings.json

+1 −0
Original line number Diff line number Diff line
@@ -60,6 +60,7 @@ 
  "cSpell.words": [

    "aarch64",

    "activitypub",

    "activitystreams",

    "aitertools",

    "apidoc",

    "bccs",

CHANGES.md

+7 −0
Original line number Diff line number Diff line
@@ -8,6 +8,12 @@ Version 1.1.0 


To be released.



 -  Added utility functions for traversing remote collections. [[#150]]



     -  Added `Context.traverseCollection()` method.

     -  Added `traverseCollection()` function.

     -  Added `TraverseCollectionOptions` interface.



 -  Added `EmojiReact` class to Activity Vocabulary API.  [[FEP-c0e0]]



 -  Added `DidService` class to Activity Vocabulary API.
@@ -53,6 +59,7 @@ To be released. 
[FEP-c0e0]: https://w3id.org/fep/c0e0

[FEP-9091]: https://w3id.org/fep/9091

[#146]: https://github.com/dahlia/fedify/issues/146

[#150]: https://github.com/dahlia/fedify/issues/150





Version 1.0.2

docs/manual/context.md

+26 −0
Original line number Diff line number Diff line
@@ -403,3 +403,29 @@ const note = await ctx.lookupObject( 
> See the [*Getting an authenticated

> `DocumentLoader`*](#getting-an-authenticated-documentloader)

> section for details.





Traversing remote collections

-----------------------------



*This API is available since Fedify 1.1.0.*



Sometimes you need to traverse a remote collection from the beginning

to the end, such as an actor's outbox, an actor's followers collection,

and so on.  The `Context.traverseCollection()` method plays a role in such

cases.  The following shows an example of traversing an actor's outbox:



~~~~ typescript

import { type Context, isActor } from "@fedify/fedify";

const ctx = null as unknown as Context<void>;

// ---cut-before---

const actor = await ctx.lookupObject("@hongminhee@fosstodon.org");

if (isActor(actor)) {

  const outbox = await actor.getOutbox();

  if (outbox != null) {

    for await (const activity of ctx.traverseCollection(outbox)) {

      console.log(activity);

    }

  }

}

~~~~

docs/manual/vocab.md

+7 −0
Original line number Diff line number Diff line
@@ -310,6 +310,13 @@ See the [*Looking up remote objects* 
section](./context.md#looking-up-remote-objects) in the *Context* docs.





Traversing remote collections

-----------------------------



See the [*Traversing remote collections* 

section](./context.md#traversing-remote-collections) in the *Context* docs.





JSON-LD

-------

src/federation/context.ts

+34 −2
Original line number Diff line number Diff line 
import type { DocumentLoader } from "../runtime/docloader.ts";

import type { Actor, Recipient } from "../vocab/actor.ts";

import type { LookupObjectOptions } from "../vocab/lookup.ts";

import type {

  LookupObjectOptions,

  TraverseCollectionOptions,

} from "../vocab/lookup.ts";

import type {

  Activity,

  Collection,

  CryptographicKey,

  Link,

  Multikey,

  Object,

} from "../vocab/mod.ts";

} from "../vocab/vocab.ts";

import type { SenderKeyPair } from "./send.ts";



/**
@@ -241,6 +246,33 @@ export interface Context<TContextData> { 
    options?: LookupObjectOptions,

  ): Promise<Object | null>;



  /**

   * Traverses a collection, yielding each item in the collection.

   * If the collection is paginated, it will fetch the next page

   * automatically.

   *

   * @example

   * ``` typescript

   * const collection = await ctx.lookupObject(collectionUrl);

   * if (collection instanceof Collection) {

   *   for await (const item of ctx.traverseCollection(collection)) {

   *     console.log(item.id?.href);

   *   }

   * }

   * ```

   *

   * It's almost the same as the {@link traverseCollection} function, but it

   * uses the context's document loader and context loader by default.

   * @param collection The collection to traverse.

   * @param options Options for traversing the collection.

   * @returns An async iterable of each item in the collection.

   * @since 1.1.0

   */

  traverseCollection(

    collection: Collection,

    options?: TraverseCollectionOptions,

  ): AsyncIterable<Object | Link>;



  /**

   * Sends an activity to recipients' inboxes.

   * @param sender The sender's identifier or the sender's username or