@fedify/botkit-redis 0.5.0-dev.0

package/README.md

@@ -0,0 +1,106 @@
+@fedify/botkit-redis
+====================
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+[![GitHub Actions][GitHub Actions badge]][GitHub Actions]
+
+This package is a [Redis]-based repository implementation for [BotKit].  It
+provides shared persistent storage for bots running on either [Deno] or
+[Node.js], using Redis data structures for BotKit repository data.
+
+[JSR badge]: https://jsr.io/badges/@fedify/botkit-redis
+[JSR]: https://jsr.io/@fedify/botkit-redis
+[npm badge]: https://img.shields.io/npm/v/@fedify/botkit-redis?logo=npm
+[npm]: https://www.npmjs.com/package/@fedify/botkit-redis
+[GitHub Actions badge]: https://github.com/fedify-dev/botkit/actions/workflows/main.yaml/badge.svg
+[GitHub Actions]: https://github.com/fedify-dev/botkit/actions/workflows/main.yaml
+[Redis]: https://redis.io/
+[BotKit]: https://botkit.fedify.dev/
+[Deno]: https://deno.land/
+[Node.js]: https://nodejs.org/
+
+
+Installation
+------------
+
+~~~~ sh
+deno add jsr:@fedify/botkit-redis
+npm  add     @fedify/botkit-redis
+pnpm add     @fedify/botkit-redis
+yarn add     @fedify/botkit-redis
+~~~~
+
+
+Usage
+-----
+
+The `RedisRepository` can be used as a drop-in repository implementation for
+BotKit:
+
+~~~~ typescript
+import { createBot, MemoryKvStore } from "@fedify/botkit";
+import { RedisRepository } from "@fedify/botkit-redis";
+
+const bot = createBot({
+  username: "mybot",
+  kv: new MemoryKvStore(),
+  repository: new RedisRepository({
+    url: "redis://localhost:6379/0",
+    prefix: "botkit",
+  }),
+});
+~~~~
+
+You can also inject an existing node-redis client.  In that case the
+repository does not own the client and `close()` will not shut it down:
+
+~~~~ typescript
+import { RedisRepository } from "@fedify/botkit-redis";
+import { createClient } from "redis";
+
+const client = createClient({ url: "redis://localhost:6379/0" });
+await client.connect();
+
+const repository = new RedisRepository({
+  client,
+  prefix: "botkit",
+});
+~~~~
+
+
+Options
+-------
+
+The `RedisRepository` constructor accepts the following options:
+
+ -  **`url`**: A Redis connection string for an internally managed client.
+
+ -  **`client`**: An existing node-redis compatible client to use.
+
+ -  **`prefix`** (optional): Redis key prefix used for BotKit data.  Defaults
+    to `"botkit"`.
+
+ -  **`clientOptions`** (optional): Additional node-redis client options.
+    This option is only valid together with `url`.
+
+The options are mutually exclusive: use either `client` or `url`.
+
+
+Features
+--------
+
+ -  **Cross-runtime**: Works with both Deno and Node.js using node-redis.
+
+ -  **Shared persistent storage**: Suitable for multi-process deployments
+    backed by Redis.
+
+ -  **Key namespacing**: Keeps BotKit data under a configurable Redis prefix.
+
+ -  **Full `Repository` API**: Implements BotKit repository storage for key
+    pairs, messages, followers, follows, followees, quote authorizations, and
+    poll votes.
+
+ -  **Explicit resource ownership**: Repositories created from a URL own their
+    Redis client, while repositories created from an injected client leave
+    lifecycle control to the caller.

package/dist/mod.d.ts

@@ -0,0 +1,129 @@
+import { ActorScopedRepository, Repository, RepositoryGetFollowersOptions, RepositoryGetMessagesOptions, Uuid } from "@fedify/botkit/repository";
+import { Actor, Announce, Create, Follow, QuoteAuthorization } from "@fedify/vocab";
+import { RedisClientOptions } from "redis";
+
+//#region src/mod.d.ts
+interface RedisClientLike {
+  readonly isOpen?: boolean;
+  connect?(): Promise<unknown>;
+  quit?(): Promise<unknown>;
+  close?(): Promise<unknown> | unknown;
+  sendCommand(args: readonly string[]): Promise<unknown>;
+}
+interface RedisRepositoryOptionsBase {
+  /**
+   * The Redis key prefix under which all BotKit data is stored.
+   * @default `"botkit"`
+   */
+  readonly prefix?: string;
+}
+interface RedisRepositoryOptionsWithClient extends RedisRepositoryOptionsBase {
+  /**
+   * A pre-configured Redis client to use.  It must already be connected.
+   */
+  readonly client: RedisClientLike;
+  /**
+   * Disallowed when `client` is provided.
+   */
+  readonly url?: never;
+  /**
+   * Disallowed when `client` is provided.
+   */
+  readonly clientOptions?: never;
+}
+interface RedisRepositoryOptionsWithUrl extends RedisRepositoryOptionsBase {
+  /**
+   * A Redis connection string to connect with.
+   */
+  readonly url: string | URL;
+  /**
+   * Disallowed when `url` is provided.
+   */
+  readonly client?: never;
+  /**
+   * Additional node-redis client options.
+   */
+  readonly clientOptions?: Omit<RedisClientOptions, "url">;
+}
+/**
+ * Options for creating a Redis repository.
+ * @since 0.5.0
+ */
+type RedisRepositoryOptions = RedisRepositoryOptionsWithClient | RedisRepositoryOptionsWithUrl;
+/**
+ * A repository for storing bot data using Redis.
+ * @since 0.5.0
+ */
+declare class RedisRepository implements Repository, AsyncDisposable {
+  private readonly client;
+  private readonly ownsClient;
+  private readonly ready;
+  /**
+   * The Redis key prefix under which all BotKit data is stored.
+   */
+  readonly prefix: string;
+  /**
+   * Creates a new Redis repository.
+   * @param options The options for creating the repository.
+   */
+  constructor(options: RedisRepositoryOptions);
+  [Symbol.asyncDispose](): Promise<void>;
+  /**
+   * Closes the owned Redis connection.
+   */
+  close(): Promise<void>;
+  private key;
+  private botKey;
+  private command;
+  private get;
+  private set;
+  private del;
+  private sAdd;
+  private sRem;
+  private sCard;
+  private zAdd;
+  private zRem;
+  private zRange;
+  private zRangeByScore;
+  private zCard;
+  private nextSequence;
+  private withRedisLock;
+  setKeyPairs(identifier: string, keyPairs: CryptoKeyPair[]): Promise<void>;
+  getKeyPairs(identifier: string): Promise<CryptoKeyPair[] | undefined>;
+  addMessage(identifier: string, id: Uuid, activity: Create | Announce): Promise<void>;
+  updateMessage(identifier: string, id: Uuid, updater: (existing: Create | Announce) => Create | Announce | undefined | Promise<Create | Announce | undefined>): Promise<boolean>;
+  removeMessage(identifier: string, id: Uuid): Promise<Create | Announce | undefined>;
+  getMessages(identifier: string, options?: RepositoryGetMessagesOptions): AsyncIterable<Create | Announce>;
+  getMessage(identifier: string, id: Uuid): Promise<Create | Announce | undefined>;
+  countMessages(identifier: string): Promise<number>;
+  addFollower(identifier: string, followId: URL, follower: Actor): Promise<void>;
+  removeFollower(identifier: string, followId: URL, followerId: URL): Promise<Actor | undefined>;
+  private cleanupFollower;
+  hasFollower(identifier: string, followerId: URL): Promise<boolean>;
+  getFollowers(identifier: string, options?: RepositoryGetFollowersOptions): AsyncIterable<Actor>;
+  countFollowers(identifier: string): Promise<number>;
+  addSentFollow(identifier: string, id: Uuid, follow: Follow): Promise<void>;
+  removeSentFollow(identifier: string, id: Uuid): Promise<Follow | undefined>;
+  getSentFollow(identifier: string, id: Uuid): Promise<Follow | undefined>;
+  addFollowee(identifier: string, followeeId: URL, follow: Follow): Promise<void>;
+  removeFollowee(identifier: string, followeeId: URL): Promise<Follow | undefined>;
+  getFollowee(identifier: string, followeeId: URL): Promise<Follow | undefined>;
+  findFollowedBots(followeeId: URL): AsyncIterable<string>;
+  addQuoteAuthorization(identifier: string, id: Uuid, authorization: QuoteAuthorization): Promise<void>;
+  getQuoteAuthorization(identifier: string, id: Uuid): Promise<QuoteAuthorization | undefined>;
+  findQuoteAuthorization(identifier: string, interactingObject: URL): Promise<QuoteAuthorization | undefined>;
+  removeQuoteAuthorization(identifier: string, id: Uuid): Promise<QuoteAuthorization | undefined>;
+  addQuoteAuthorizationReference(identifier: string, authorization: URL, messageId: Uuid, attribution?: URL): Promise<void>;
+  findQuoteAuthorizationReference(identifier: string, authorization: URL): Promise<Uuid | undefined>;
+  findQuoteAuthorizationReferenceIdentifiers(authorization: URL): AsyncIterable<string>;
+  findQuoteAuthorizationReferenceAttribution(identifier: string, authorization: URL): Promise<URL | undefined>;
+  removeQuoteAuthorizationReference(identifier: string, authorization: URL): Promise<void>;
+  vote(identifier: string, messageId: Uuid, voterId: URL, option: string): Promise<void>;
+  countVoters(identifier: string, messageId: Uuid): Promise<number>;
+  countVotes(identifier: string, messageId: Uuid): Promise<Readonly<Record<string, number>>>;
+  forIdentifier(identifier: string): ActorScopedRepository;
+  private quoteAuthorizationLockKey;
+}
+//#endregion
+export { RedisRepository, RedisRepositoryOptions };
+//# sourceMappingURL=mod.d.ts.map

package/dist/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","names":[],"sources":["../src/mod.ts"],"sourcesContent":[],"mappings":"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"}