storybooker 0.19.3 → 0.22.0-canary.0

package/src/adapters/gcp-storage.ts

@@ -0,0 +1,141 @@
+import type { File, Storage } from "@google-cloud/storage";
+import { Buffer } from "node:buffer";
+import { Readable } from "node:stream";
+import type streamWeb from "node:stream/web";
+import { StorageAdapterErrors, type StorageAdapter } from "./_internal/storage.ts";
+
+export class GcpGcsStorageService implements StorageAdapter {
+  #client: Storage;
+
+  constructor(client: Storage) {
+    this.#client = client;
+  }
+
+  metadata: StorageAdapter["metadata"] = { name: "Google Cloud Storage" };
+
+  createContainer: StorageAdapter["createContainer"] = async (containerId, _options) => {
+    try {
+      const bucketName = genBucketNameFromContainerId(containerId);
+      await this.#client.createBucket(bucketName, {});
+    } catch (error) {
+      throw new StorageAdapterErrors.ContainerAlreadyExistsError(containerId, error);
+    }
+  };
+
+  deleteContainer: StorageAdapter["deleteContainer"] = async (containerId, _options) => {
+    try {
+      const bucketName = genBucketNameFromContainerId(containerId);
+      await this.#client.bucket(bucketName).delete();
+    } catch (error) {
+      throw new StorageAdapterErrors.ContainerDoesNotExistError(containerId, error);
+    }
+  };
+
+  hasContainer: StorageAdapter["hasContainer"] = async (containerId, _options) => {
+    const bucketName = genBucketNameFromContainerId(containerId);
+    const [exists] = await this.#client.bucket(bucketName).exists();
+    return exists;
+  };
+
+  listContainers: StorageAdapter["listContainers"] = async (_options) => {
+    const [buckets] = await this.#client.getBuckets();
+    return buckets.map((bucket) => bucket.name);
+  };
+
+  deleteFiles: StorageAdapter["deleteFiles"] = async (containerId, filePathsOrPrefix, _options) => {
+    const bucketName = genBucketNameFromContainerId(containerId);
+    const bucket = this.#client.bucket(bucketName);
+
+    if (typeof filePathsOrPrefix === "string") {
+      // Delete all files with the prefix
+      await bucket.deleteFiles({ prefix: filePathsOrPrefix });
+    } else {
+      // Delete specific files
+      await Promise.all(
+        filePathsOrPrefix.map(
+          async (filepath) => await bucket.file(filepath).delete({ ignoreNotFound: true }),
+        ),
+      );
+    }
+  };
+
+  uploadFiles: StorageAdapter["uploadFiles"] = async (containerId, files, _options) => {
+    const bucketName = genBucketNameFromContainerId(containerId);
+    const bucket = this.#client.bucket(bucketName);
+
+    await Promise.allSettled(
+      files.map(async ({ content, path, mimeType }) => {
+        await uploadFileToGcs(bucket.file(path), content, mimeType);
+      }),
+    );
+  };
+
+  hasFile: StorageAdapter["hasFile"] = async (containerId, filepath, _options) => {
+    const bucketName = genBucketNameFromContainerId(containerId);
+    const file = this.#client.bucket(bucketName).file(filepath);
+    const [exists] = await file.exists();
+    return exists;
+  };
+
+  downloadFile: StorageAdapter["downloadFile"] = async (containerId, filepath, _options) => {
+    const bucketName = genBucketNameFromContainerId(containerId);
+    const file = this.#client.bucket(bucketName).file(filepath);
+
+    const [exists] = await file.exists();
+    if (!exists) {
+      throw new StorageAdapterErrors.FileDoesNotExistError(containerId, filepath);
+    }
+
+    const [metadata] = await file.getMetadata();
+    const mimeType = metadata.contentType;
+
+    const readable = file.createReadStream();
+    const content = Readable.toWeb(readable);
+
+    return {
+      content: content as ReadableStream,
+      mimeType,
+      path: filepath,
+    };
+  };
+}
+
+function genBucketNameFromContainerId(containerId: string): string {
+  // GCS bucket names: lowercase, numbers, dashes, dots, 3-63 chars
+  return containerId
+    .replaceAll(/[^\w.-]+/g, "-")
+    .replaceAll(/^-+|-+$/g, "")
+    .toLowerCase()
+    .slice(0, 63);
+}
+
+async function uploadFileToGcs(
+  file: File,
+  data: Blob | string | ReadableStream,
+  mimeType: string,
+): Promise<void> {
+  if (typeof data === "string" || data instanceof Buffer) {
+    await file.save(data, { contentType: mimeType });
+    return;
+  }
+
+  if (data instanceof Blob) {
+    const buffer = Buffer.from(await data.arrayBuffer());
+    await file.save(buffer, { contentType: mimeType });
+    return;
+  }
+
+  const readable =
+    data instanceof ReadableStream ? Readable.fromWeb(data as streamWeb.ReadableStream) : data;
+
+  if (readable instanceof Readable) {
+    // Node.js Readable stream
+    await new Promise<void>((resolve, reject) => {
+      const writeStream = file.createWriteStream({ contentType: mimeType });
+      readable.pipe(writeStream).on("finish", resolve).on("error", reject);
+    });
+    return;
+  }
+
+  throw new Error(`Unknown file type`);
+}

package/src/adapters/mysql.ts

@@ -0,0 +1,296 @@
+// oxlint-disable max-lines-per-function
+// oxlint-disable no-unsafe-member-access
+
+import {
+  DatabaseAdapterErrors,
+  type DatabaseAdapter,
+  type DatabaseAdapterOptions,
+  type DatabaseDocumentListOptions,
+  type StoryBookerDatabaseDocument,
+} from "./_internal/database.ts";
+
+// Define a generic SQL connection interface that works with multiple MySQL libraries
+export interface MySQLConnection {
+  connect?(): Promise<void>;
+  execute<Data>(query: string, params?: unknown[]): Promise<[Data]>;
+  query<Data>(query: string, params?: unknown[]): Promise<[Data]>;
+  end?(): Promise<void>;
+}
+
+/**
+ * MySQL database adapter for StoryBooker.
+ * Uses tables to represent collections and rows to represent documents.
+ *
+ * Table structure:
+ * - Each collection becomes a table with name: `sb_{collectionId}`
+ * - Each table has columns: id (VARCHAR PRIMARY KEY), data (JSON), created_at (TIMESTAMP), updated_at (TIMESTAMP)
+ * - Collections metadata stored in `sb_collections` table
+ *
+ * Compatible with mysql2, mysql, and other MySQL libraries that implement the connection interface.
+ */
+export class MySQLDatabaseAdapter implements DatabaseAdapter {
+  #connection: MySQLConnection;
+  #tablePrefix: string;
+
+  constructor(connection: MySQLConnection, tablePrefix = "sb") {
+    this.#connection = connection;
+    this.#tablePrefix = tablePrefix;
+  }
+
+  metadata: DatabaseAdapter["metadata"] = { name: "MySQL" };
+
+  init: DatabaseAdapter["init"] = async (_options) => {
+    // Create collections metadata table
+    try {
+      const collectionsTable = `${this.#tablePrefix}_collections`;
+      await this.#connection.connect?.();
+      await this.#connection.execute(`
+        CREATE TABLE IF NOT EXISTS \`${collectionsTable}\` (
+          id VARCHAR(255) PRIMARY KEY,
+          created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+          ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+          `);
+    } catch (error) {
+      throw new DatabaseAdapterErrors.DatabaseNotInitializedError(error);
+    }
+  };
+
+  // Helper methods
+  #getTableName(collectionId: string): string {
+    return `${this.#tablePrefix}_${collectionId}`;
+  }
+
+  #getCollectionsTableName(): string {
+    return `${this.#tablePrefix}_collections`;
+  }
+
+  // oxlint-disable-next-line class-methods-use-this
+  #formatDocumentRow<Document extends StoryBookerDatabaseDocument>(row: { id: string }): Document {
+    if ("data" in row && typeof row["data"] === "string") {
+      return { id: row.id, ...JSON.parse(row["data"]) } as Document;
+    }
+    return row as unknown as Document;
+  }
+
+  listCollections: DatabaseAdapter["listCollections"] = async (_options) => {
+    const collectionsTable = this.#getCollectionsTableName();
+    const [rows] = await this.#connection.execute<StoryBookerDatabaseDocument[]>(
+      `SELECT id FROM \`${collectionsTable}\``,
+    );
+    return rows.map((row) => row.id);
+  };
+
+  createCollection: DatabaseAdapter["createCollection"] = async (collectionId, _options) => {
+    try {
+      const tableName = this.#getTableName(collectionId);
+      const collectionsTable = this.#getCollectionsTableName();
+
+      // Create the collection table
+      await this.#connection.execute(`
+      CREATE TABLE IF NOT EXISTS \`${tableName}\` (
+        id VARCHAR(255) PRIMARY KEY,
+        data JSON NOT NULL,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+        INDEX idx_created_at (created_at)
+      ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+    `);
+
+      // Register collection
+      await this.#connection.execute(`INSERT IGNORE INTO \`${collectionsTable}\` (id) VALUES (?)`, [
+        collectionId,
+      ]);
+    } catch (error) {
+      throw new DatabaseAdapterErrors.CollectionAlreadyExistsError(collectionId, error);
+    }
+  };
+
+  hasCollection: DatabaseAdapter["hasCollection"] = async (collectionId, _options) => {
+    const collectionsTable = this.#getCollectionsTableName();
+    const [rows] = await this.#connection.execute<StoryBookerDatabaseDocument[]>(
+      `SELECT 1 FROM \`${collectionsTable}\` WHERE id = ? LIMIT 1`,
+      [collectionId],
+    );
+    return rows.length > 0;
+  };
+
+  deleteCollection: DatabaseAdapter["deleteCollection"] = async (collectionId, _options) => {
+    const tableName = this.#getTableName(collectionId);
+    const collectionsTable = this.#getCollectionsTableName();
+
+    try {
+      // Drop the table
+      await this.#connection.execute(`DROP TABLE IF EXISTS \`${tableName}\``);
+
+      // Remove from collections registry
+      await this.#connection.execute(`DELETE FROM \`${collectionsTable}\` WHERE id = ?`, [
+        collectionId,
+      ]);
+    } catch (error) {
+      throw new DatabaseAdapterErrors.CollectionDoesNotExistError(collectionId, error);
+    }
+  };
+
+  listDocuments: DatabaseAdapter["listDocuments"] = async <
+    Document extends StoryBookerDatabaseDocument,
+  >(
+    collectionId: string,
+    listOptions: DatabaseDocumentListOptions<Document>,
+    _options: DatabaseAdapterOptions,
+  ): Promise<Document[]> => {
+    const tableName = this.#getTableName(collectionId);
+
+    let query = `SELECT id, data FROM \`${tableName}\``;
+    const params: unknown[] = [];
+
+    // Apply string-based filtering (basic WHERE clause support)
+    if (listOptions?.filter && typeof listOptions.filter === "string") {
+      query += ` WHERE ${listOptions.filter}`;
+    }
+
+    // Apply sorting
+    if (listOptions?.sort && listOptions.sort === "latest") {
+      query += ` ORDER BY created_at DESC`;
+
+      // Function-based sorting will be applied in memory
+    }
+
+    // Apply limit
+    if (listOptions?.limit && listOptions.limit > 0) {
+      query += ` LIMIT ?`;
+      params.push(listOptions.limit);
+    }
+
+    const [rows] = await this.#connection.execute<Document[]>(query, params);
+    let documents: Document[] = [];
+    for (const row of rows) {
+      documents.push(this.#formatDocumentRow<Document>(row));
+    }
+
+    // Apply function-based filtering
+    const filterFn =
+      listOptions?.filter && typeof listOptions.filter === "function"
+        ? listOptions.filter
+        : undefined;
+    if (filterFn) {
+      documents = documents.filter((item) => filterFn(item));
+    }
+
+    // Apply function-based sorting
+    if (listOptions?.sort && typeof listOptions.sort === "function") {
+      documents.sort(listOptions.sort);
+    }
+
+    // Apply field selection (projection)
+    if (listOptions?.select && listOptions.select.length > 0) {
+      documents = documents.map((doc) => {
+        const projected = { id: doc.id } as Document;
+        // oxlint-disable-next-line no-non-null-assertion
+        for (const field of listOptions.select!) {
+          if (field in doc) {
+            // oxlint-disable-next-line no-explicit-any
+            (projected as any)[field] = (doc as any)[field];
+          }
+        }
+        return projected;
+      });
+    }
+
+    return documents;
+  };
+
+  getDocument: DatabaseAdapter["getDocument"] = async <
+    Document extends StoryBookerDatabaseDocument,
+  >(
+    collectionId: string,
+    documentId: string,
+    _options: DatabaseAdapterOptions,
+  ): Promise<Document> => {
+    const tableName = this.#getTableName(collectionId);
+    const [rows] = await this.#connection.execute<Document[]>(
+      `SELECT id, data FROM \`${tableName}\` WHERE id = ? LIMIT 1`,
+      [documentId],
+    );
+
+    const [row] = rows;
+    if (!row) {
+      throw new DatabaseAdapterErrors.DocumentDoesNotExistError(collectionId, documentId);
+    }
+
+    return this.#formatDocumentRow<Document>(row);
+  };
+
+  hasDocument: DatabaseAdapter["hasDocument"] = async (collectionId, documentId, _options) => {
+    const tableName = this.#getTableName(collectionId);
+    const [rows] = await this.#connection.execute<Document[]>(
+      `SELECT 1 FROM \`${tableName}\` WHERE id = ? LIMIT 1`,
+      [documentId],
+    );
+    return rows.length > 0;
+  };
+
+  createDocument: DatabaseAdapter["createDocument"] = async (
+    collectionId,
+    documentData,
+    _options,
+  ) => {
+    const tableName = this.#getTableName(collectionId);
+    const { id, ...data } = documentData;
+    try {
+      await this.#connection.execute(`INSERT INTO \`${tableName}\` (id, data) VALUES (?, ?)`, [
+        id,
+        JSON.stringify(data),
+      ]);
+    } catch (error) {
+      throw new DatabaseAdapterErrors.DocumentAlreadyExistsError(
+        collectionId,
+        documentData.id,
+        error,
+      );
+    }
+  };
+
+  updateDocument: DatabaseAdapter["updateDocument"] = async (
+    collectionId,
+    documentId,
+    documentData,
+  ) => {
+    const tableName = this.#getTableName(collectionId);
+
+    // Get existing document
+    const [rows] = await this.#connection.execute<StoryBookerDatabaseDocument[]>(
+      `SELECT data FROM \`${tableName}\` WHERE id = ? LIMIT 1`,
+      [documentId],
+    );
+
+    const [row] = rows;
+    if (!row) {
+      throw new DatabaseAdapterErrors.DocumentDoesNotExistError(collectionId, documentId);
+    }
+
+    const existingData =
+      "data" in row && typeof row["data"] === "string" ? JSON.parse(row["data"]) : null;
+    const updatedData = { ...existingData, ...documentData };
+
+    await this.#connection.execute(`UPDATE \`${tableName}\` SET data = ? WHERE id = ?`, [
+      JSON.stringify(updatedData),
+      documentId,
+    ]);
+  };
+
+  deleteDocument: DatabaseAdapter["deleteDocument"] = async (
+    collectionId,
+    documentId,
+    _options,
+  ) => {
+    const tableName = this.#getTableName(collectionId);
+    const [result] = await this.#connection.execute<{ affectedRows: number }>(
+      `DELETE FROM \`${tableName}\` WHERE id = ?`,
+      [documentId],
+    );
+
+    if (result.affectedRows === 0) {
+      throw new DatabaseAdapterErrors.DocumentDoesNotExistError(collectionId, documentId);
+    }
+  };
+}

package/src/adapters/redis.ts

@@ -0,0 +1,242 @@
+// oxlint-disable no-explicit-any
+// oxlint-disable no-unsafe-member-access
+
+import type { RedisClientType } from "redis";
+import {
+  DatabaseAdapterErrors,
+  type DatabaseAdapter,
+  type DatabaseAdapterOptions,
+  type DatabaseDocumentListOptions,
+  type StoryBookerDatabaseDocument,
+} from "./_internal/database.ts";
+
+/**
+ * Redis database adapter for StoryBooker.
+ * Uses key prefixes to simulate collections since Redis is key-value store.
+ *
+ * Key structure: `collection:{collectionId}:doc:{documentId}`
+ * Collections list key: `collections`
+ *
+ * Compatible with all Redis services (Redis Cloud, AWS ElastiCache, Azure Cache, etc.)
+ */
+export class RedisDatabaseAdapter implements DatabaseAdapter {
+  #client: RedisClientType;
+  #keyPrefix: string;
+
+  constructor(client: RedisClientType, keyPrefix = "sbr") {
+    this.#client = client;
+    this.#keyPrefix = keyPrefix;
+  }
+
+  metadata: DatabaseAdapter["metadata"] = { name: "Redis" };
+
+  init: DatabaseAdapter["init"] = async (_options) => {
+    // Ensure Redis connection is ready
+    if (!this.#client.isReady) {
+      try {
+        await this.#client.connect();
+      } catch (error) {
+        throw new DatabaseAdapterErrors.DatabaseNotInitializedError(error);
+      }
+    }
+  };
+
+  // Helper methods for key generation
+  //   #getCollectionKey(collectionId: string): string {
+  //     return `${this.#keyPrefix}:collection:${collectionId}`;
+  //   }
+
+  #getDocumentKey(collectionId: string, documentId: string): string {
+    return `${this.#keyPrefix}:collection:${collectionId}:doc:${documentId}`;
+  }
+
+  #getCollectionsSetKey(): string {
+    return `${this.#keyPrefix}:collections`;
+  }
+
+  listCollections: DatabaseAdapter["listCollections"] = async (_options) => {
+    const collections = await this.#client.sMembers(this.#getCollectionsSetKey());
+    return collections;
+  };
+
+  createCollection: DatabaseAdapter["createCollection"] = async (collectionId, _options) => {
+    try {
+      // Add collection to the set of collections
+      await this.#client.sAdd(this.#getCollectionsSetKey(), collectionId);
+    } catch (error) {
+      throw new DatabaseAdapterErrors.CollectionAlreadyExistsError(collectionId, error);
+    }
+  };
+
+  hasCollection: DatabaseAdapter["hasCollection"] = async (collectionId, _options) => {
+    const exists = await this.#client.sIsMember(this.#getCollectionsSetKey(), collectionId);
+    return exists > 0;
+  };
+
+  deleteCollection: DatabaseAdapter["deleteCollection"] = async (collectionId, _options) => {
+    try {
+      // Get all document keys for this collection
+      const pattern = this.#getDocumentKey(collectionId, "*");
+      const keys = await this.#client.keys(pattern);
+
+      // Delete all documents in the collection
+      if (keys.length > 0) {
+        await this.#client.del(keys);
+      }
+
+      // Remove collection from the set
+      await this.#client.sRem(this.#getCollectionsSetKey(), collectionId);
+    } catch (error) {
+      throw new DatabaseAdapterErrors.CollectionDoesNotExistError(collectionId, error);
+    }
+  };
+
+  listDocuments: DatabaseAdapter["listDocuments"] = async <
+    Document extends StoryBookerDatabaseDocument,
+  >(
+    collectionId: string,
+    listOptions: DatabaseDocumentListOptions<Document>,
+    _options: DatabaseAdapterOptions,
+  ): Promise<Document[]> => {
+    const pattern = this.#getDocumentKey(collectionId, "*");
+    const keys = await this.#client.keys(pattern);
+
+    if (keys.length === 0) {
+      return [];
+    }
+
+    // Get all documents
+    const values = await this.#client.mGet(keys);
+    const documents: Document[] = values
+      .filter((value): value is string => value !== null)
+      .map((value) => JSON.parse(value) as Document);
+
+    // Apply filtering
+    let filteredDocs = documents;
+    const filterFn =
+      listOptions?.filter && typeof listOptions.filter === "function"
+        ? listOptions.filter
+        : undefined;
+    if (filterFn) {
+      filteredDocs = documents.filter((doc) => filterFn(doc));
+    }
+    // String filters could be implemented as key pattern matching if needed
+
+    // Apply sorting
+    if (listOptions?.sort) {
+      if (typeof listOptions.sort === "function") {
+        filteredDocs.sort(listOptions.sort);
+      } else if (listOptions.sort === "latest") {
+        // Assume documents have a createdAt or similar timestamp field
+        filteredDocs.sort((docA, docB) => {
+          const aTime = (docA as any).createdAt ?? (docA as any).timestamp ?? 0;
+          const bTime = (docB as any).createdAt ?? (docB as any).timestamp ?? 0;
+          return bTime - aTime; // Descending order (latest first)
+        });
+      }
+    }
+
+    // Apply limit
+    if (listOptions?.limit && listOptions.limit > 0) {
+      filteredDocs = filteredDocs.slice(0, listOptions.limit);
+    }
+
+    // // Apply select (field projection)
+    // if (listOptions?.select && listOptions.select.length > 0) {
+    //   filteredDocs = filteredDocs.map((doc) => {
+    //     const projected = { id: doc.id } as Document;
+    //     // oxlint-disable-next-line no-non-null-assertion
+    //     for (const field of listOptions.select!) {
+    //       if (field in doc) {
+    //         projected[field] = (doc as any)[field];
+    //       }
+    //     }
+    //     return projected;
+    //   });
+    // }
+
+    return filteredDocs;
+  };
+
+  getDocument: DatabaseAdapter["getDocument"] = async <
+    Document extends StoryBookerDatabaseDocument,
+  >(
+    collectionId: string,
+    documentId: string,
+    _options: DatabaseAdapterOptions,
+  ): Promise<Document> => {
+    const key = this.#getDocumentKey(collectionId, documentId);
+    const value = await this.#client.get(key);
+
+    if (!value) {
+      throw new DatabaseAdapterErrors.DocumentDoesNotExistError(collectionId, documentId);
+    }
+
+    const document: Document = JSON.parse(value);
+    return document;
+  };
+
+  hasDocument: DatabaseAdapter["hasDocument"] = async (collectionId, documentId, _options) => {
+    const key = this.#getDocumentKey(collectionId, documentId);
+    const exists = await this.#client.exists(key);
+    return exists === 1;
+  };
+
+  createDocument: DatabaseAdapter["createDocument"] = async (
+    collectionId,
+    documentData,
+    _options,
+  ) => {
+    // Ensure collection exists
+    try {
+      await this.#client.sAdd(this.#getCollectionsSetKey(), collectionId);
+    } catch (error) {
+      throw new DatabaseAdapterErrors.CollectionDoesNotExistError(collectionId, error);
+    }
+
+    try {
+      const key = this.#getDocumentKey(collectionId, documentData.id);
+      const value = JSON.stringify(documentData);
+      await this.#client.set(key, value);
+    } catch (error) {
+      throw new DatabaseAdapterErrors.DocumentAlreadyExistsError(
+        collectionId,
+        documentData.id,
+        error,
+      );
+    }
+  };
+
+  updateDocument: DatabaseAdapter["updateDocument"] = async (
+    collectionId,
+    documentId,
+    documentData,
+  ) => {
+    const key = this.#getDocumentKey(collectionId, documentId);
+
+    // Get existing document
+    const existingValue = await this.#client.get(key);
+    if (!existingValue) {
+      throw new DatabaseAdapterErrors.DocumentDoesNotExistError(collectionId, documentId);
+    }
+
+    const existingDoc = JSON.parse(existingValue);
+    const updatedDoc = { ...existingDoc, ...documentData };
+
+    const value = JSON.stringify(updatedDoc);
+    await this.#client.set(key, value);
+  };
+
+  deleteDocument: DatabaseAdapter["deleteDocument"] = async (
+    collectionId,
+    documentId,
+    _options,
+  ) => {
+    const key = this.#getDocumentKey(collectionId, documentId);
+    const deleted = await this.#client.del(key);
+
+    if (deleted === 0) {
+      throw new DatabaseAdapterErrors.DocumentDoesNotExistError(collectionId, documentId);
+    }
+  };
+}