@fedify/botkit-postgres 0.4.0-dev.0

package/README.md

@@ -0,0 +1,130 @@
+@fedify/botkit-postgres
+=======================
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+[![GitHub Actions][GitHub Actions badge]][GitHub Actions]
+
+This package is a [PostgreSQL]-based repository implementation for [BotKit].
+It provides persistent shared storage for bots running on either [Deno] or
+[Node.js], supports connection pooling through [Postgres.js], and stores BotKit
+repository data in ordinary PostgreSQL tables under a dedicated schema.
+
+[JSR badge]: https://jsr.io/badges/@fedify/botkit-postgres
+[JSR]: https://jsr.io/@fedify/botkit-postgres
+[npm badge]: https://img.shields.io/npm/v/@fedify/botkit-postgres?logo=npm
+[npm]: https://www.npmjs.com/package/@fedify/botkit-postgres
+[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
+[PostgreSQL]: https://www.postgresql.org/
+[BotKit]: https://botkit.fedify.dev/
+[Deno]: https://deno.land/
+[Node.js]: https://nodejs.org/
+[Postgres.js]: https://github.com/porsager/postgres
+
+
+Installation
+------------
+
+~~~~ sh
+deno add jsr:@fedify/botkit-postgres
+npm  add     @fedify/botkit-postgres
+pnpm add     @fedify/botkit-postgres
+yarn add     @fedify/botkit-postgres
+~~~~
+
+
+Usage
+-----
+
+The `PostgresRepository` can be used as a drop-in repository implementation for
+BotKit:
+
+~~~~ typescript
+import { createBot } from "@fedify/botkit";
+import { PostgresRepository } from "@fedify/botkit-postgres";
+
+const bot = createBot({
+  username: "mybot",
+  repository: new PostgresRepository({
+    url: "postgresql://localhost/botkit",
+    schema: "botkit",
+    maxConnections: 10,
+  }),
+});
+~~~~
+
+You can also inject an existing [Postgres.js] client.  In that case the
+repository does not own the client and `close()` will not shut it down:
+
+~~~~ typescript
+import postgres from "postgres";
+import { PostgresRepository } from "@fedify/botkit-postgres";
+
+const sql = postgres("postgresql://localhost/botkit");
+const repository = new PostgresRepository({
+  sql,
+  schema: "botkit",
+});
+~~~~
+
+
+Options
+-------
+
+The `PostgresRepository` constructor accepts the following options:
+
+ -  **`sql`**: An existing [Postgres.js] client to use.
+
+ -  **`url`**: A PostgreSQL connection string for an internally managed
+    connection pool.
+
+ -  **`schema`** (optional): The PostgreSQL schema name used for BotKit tables.
+    Defaults to `"botkit"`.
+
+ -  **`maxConnections`** (optional): Maximum number of connections for an
+    internally managed pool created from `url`.
+
+ -  **`prepare`** (optional): Whether to use prepared statements for queries.
+    Defaults to `true`.
+
+The options are mutually exclusive: use either `sql` or `url`.  The
+`maxConnections` option is only valid together with `url`.
+
+
+Schema setup
+------------
+
+The repository creates its schema and tables automatically on first use.
+If you want to provision them explicitly ahead of time, use the exported
+`initializePostgresRepositorySchema()` helper:
+
+~~~~ typescript
+import postgres from "postgres";
+import { initializePostgresRepositorySchema } from "@fedify/botkit-postgres";
+
+const sql = postgres("postgresql://localhost/botkit");
+await initializePostgresRepositorySchema(sql, "botkit");
+~~~~
+
+If you disable prepared statements, pass `false` as the third argument so
+schema initialization uses the same setting.
+
+
+Features
+--------
+
+ -  **Cross-runtime**: Works with both Deno and Node.js using [Postgres.js]
+
+ -  **Shared persistent storage**: Suitable for multi-process and
+    multi-instance deployments backed by PostgreSQL
+
+ -  **Schema namespacing**: Keeps BotKit tables grouped under a dedicated
+    PostgreSQL schema
+
+ -  **Full `Repository` API**: Implements BotKit repository storage for key
+    pairs, messages, followers, follows, followees, and poll votes
+
+ -  **Explicit resource ownership**: Repositories created from a URL own their
+    pool, while repositories created from an injected client leave lifecycle
+    control to the caller

package/dist/mod.d.ts

@@ -0,0 +1,121 @@
+import { Actor, Announce, Create, Follow } from "@fedify/vocab";
+import postgres from "postgres";
+import { Repository, RepositoryGetFollowersOptions, RepositoryGetMessagesOptions, Uuid } from "@fedify/botkit/repository";
+
+//#region src/mod.d.ts
+type Queryable = Pick<postgres.Sql, "unsafe">;
+/**
+ * Common options for creating a PostgreSQL repository.
+ * @since 0.4.0
+ */
+interface PostgresRepositoryOptionsBase {
+  /**
+   * The PostgreSQL schema name to use.
+   * @default `"botkit"`
+   */
+  readonly schema?: string;
+  /**
+   * Whether to use prepared statements for queries.
+   * @default true
+   */
+  readonly prepare?: boolean;
+}
+/**
+ * Options for creating a PostgreSQL repository from an injected client.
+ * @since 0.4.0
+ */
+interface PostgresRepositoryOptionsWithClient extends PostgresRepositoryOptionsBase {
+  /**
+   * A pre-configured PostgreSQL client to use.
+   */
+  readonly sql: postgres.Sql;
+  /**
+   * Disallowed when `sql` is provided.
+   */
+  readonly url?: never;
+  /**
+   * Disallowed when `sql` is provided.
+   */
+  readonly maxConnections?: never;
+}
+/**
+ * Options for creating a PostgreSQL repository from a connection string.
+ * @since 0.4.0
+ */
+interface PostgresRepositoryOptionsWithUrl extends PostgresRepositoryOptionsBase {
+  /**
+   * A PostgreSQL connection string to connect with.
+   */
+  readonly url: string | URL;
+  /**
+   * Disallowed when `url` is provided.
+   */
+  readonly sql?: never;
+  /**
+   * The maximum number of connections for an owned pool.
+   */
+  readonly maxConnections?: number;
+}
+/**
+ * Options for creating a PostgreSQL repository.
+ * @since 0.4.0
+ */
+type PostgresRepositoryOptions = PostgresRepositoryOptionsWithClient | PostgresRepositoryOptionsWithUrl;
+/**
+ * Initializes the PostgreSQL schema used by BotKit repositories.
+ * @param sql The PostgreSQL client to initialize the schema with.
+ * @param schema The PostgreSQL schema name to initialize.
+ * @param prepare Whether to use prepared statements for schema queries.
+ * @since 0.4.0
+ */
+declare function initializePostgresRepositorySchema(sql: Queryable, schema?: string, prepare?: boolean): Promise<void>;
+/**
+ * A repository for storing bot data using PostgreSQL.
+ * @since 0.4.0
+ */
+declare class PostgresRepository implements Repository, AsyncDisposable {
+  readonly sql: postgres.Sql;
+  readonly schema: string;
+  readonly prepare: boolean;
+  private readonly ownsSql;
+  private readonly ready;
+  constructor(options: PostgresRepositoryOptions);
+  [Symbol.asyncDispose](): Promise<void>;
+  /**
+   * Closes the underlying PostgreSQL connection pool if owned by the
+   * repository.
+   */
+  close(): Promise<void>;
+  setKeyPairs(keyPairs: CryptoKeyPair[]): Promise<void>;
+  getKeyPairs(): Promise<CryptoKeyPair[] | undefined>;
+  addMessage(id: Uuid, activity: Create | Announce): Promise<void>;
+  updateMessage(id: Uuid, updater: (existing: Create | Announce) => Create | Announce | undefined | Promise<Create | Announce | undefined>): Promise<boolean>;
+  removeMessage(id: Uuid): Promise<Create | Announce | undefined>;
+  getMessages(options?: RepositoryGetMessagesOptions): AsyncIterable<Create | Announce>;
+  getMessage(id: Uuid): Promise<Create | Announce | undefined>;
+  countMessages(): Promise<number>;
+  addFollower(followId: URL, follower: Actor): Promise<void>;
+  removeFollower(followId: URL, followerId: URL): Promise<Actor | undefined>;
+  hasFollower(followerId: URL): Promise<boolean>;
+  getFollowers(options?: RepositoryGetFollowersOptions): AsyncIterable<Actor>;
+  countFollowers(): Promise<number>;
+  addSentFollow(id: Uuid, follow: Follow): Promise<void>;
+  removeSentFollow(id: Uuid): Promise<Follow | undefined>;
+  getSentFollow(id: Uuid): Promise<Follow | undefined>;
+  addFollowee(followeeId: URL, follow: Follow): Promise<void>;
+  removeFollowee(followeeId: URL): Promise<Follow | undefined>;
+  getFollowee(followeeId: URL): Promise<Follow | undefined>;
+  vote(messageId: Uuid, voterId: URL, option: string): Promise<void>;
+  countVoters(messageId: Uuid): Promise<number>;
+  countVotes(messageId: Uuid): Promise<Readonly<Record<string, number>>>;
+  private table;
+  private lockFollowRequest;
+  private lockFollower;
+  private lockFollowers;
+  private cleanupFollower;
+  private ensureReady;
+  private query;
+}
+//#endregion
+export { PostgresRepository, PostgresRepositoryOptions, initializePostgresRepositorySchema };
+//# 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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"}