@procedures/mongo 0.0.0-stage → 0.2.0

package/src/storage/mongo-storage.ts

@@ -0,0 +1,151 @@
+/**
+ * MongoDB Storage Implementation
+ *
+ * Implements CollectionStorage<T> from client-collections, providing MongoDB
+ * as a storage backend for the collections framework.
+ */
+
+import type { Collection, Document, Filter } from "mongodb";
+import type { CollectionStorage, StorageMetadata } from "@procedures/collections";
+import { ensureConnection } from "../connection.js";
+
+/**
+ * Configuration options for MongoStorage.
+ */
+export interface MongoStorageOptions {
+  /** MongoDB collection name */
+  collection: string;
+}
+
+/**
+ * MongoDB document with string ID.
+ */
+interface MongoDoc<T> extends Document {
+  _id: string;
+  data: T;
+}
+
+/**
+ * MongoDB implementation of CollectionStorage.
+ *
+ * Stores items as documents with the structure:
+ * { _id: string, data: T }
+ *
+ * @example
+ * ```typescript
+ * const storage = new MongoStorage<User>({ collection: "users" });
+ * await storage.set("user-1", { name: "Alice", email: "alice@example.com" });
+ * const user = await storage.get("user-1");
+ * ```
+ */
+export class MongoStorage<T> implements CollectionStorage<T> {
+  private readonly collectionName: string;
+
+  constructor(options: MongoStorageOptions) {
+    this.collectionName = options.collection;
+  }
+
+  /**
+   * The collection, from the current default connection. The storage does not keep it: after a
+   * reconnect the old collection belongs to a closed client (deep dive DATA-6).
+   */
+  private async getCollection(): Promise<Collection<MongoDoc<T>>> {
+    const connection = await ensureConnection();
+    return connection.getDb().collection<MongoDoc<T>>(this.collectionName);
+  }
+
+  async get(id: string): Promise<T | undefined> {
+    const doc = await (await this.getCollection()).findOne({ _id: id } as Filter<MongoDoc<T>>);
+    return doc?.data;
+  }
+
+  async getAll(): Promise<T[]> {
+    const docs = await (await this.getCollection()).find({}).toArray();
+    return docs.map((doc) => doc.data);
+  }
+
+  async find(predicate: (item: T) => boolean): Promise<T[]> {
+    const all = await this.getAll();
+    return all.filter(predicate);
+  }
+
+  async has(id: string): Promise<boolean> {
+    const count = await (await this.getCollection()).countDocuments({ _id: id } as Filter<MongoDoc<T>>, { limit: 1 });
+    return count > 0;
+  }
+
+  async size(): Promise<number> {
+    return (await this.getCollection()).countDocuments({});
+  }
+
+  async set(id: string, value: T): Promise<void> {
+    await (await this.getCollection()).updateOne(
+      { _id: id } as Filter<MongoDoc<T>>,
+      { $set: { _id: id, data: value } as unknown as Document },
+      { upsert: true }
+    );
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const result = await (await this.getCollection()).deleteOne({ _id: id } as Filter<MongoDoc<T>>);
+    return result.deletedCount > 0;
+  }
+
+  async clear(): Promise<void> {
+    await (await this.getCollection()).deleteMany({});
+  }
+
+  async setBatch(items: Array<[string, T]>): Promise<void> {
+    if (items.length === 0) return;
+
+    const operations = items.map(([id, value]) => ({
+      updateOne: {
+        filter: { _id: id } as Filter<MongoDoc<T>>,
+        update: { $set: { _id: id, data: value } as unknown as Document },
+        upsert: true,
+      },
+    }));
+
+    await (await this.getCollection()).bulkWrite(operations);
+  }
+
+  async deleteBatch(ids: string[]): Promise<number> {
+    if (ids.length === 0) return 0;
+
+    const result = await (await this.getCollection()).deleteMany({
+      _id: { $in: ids },
+    } as Filter<MongoDoc<T>>);
+
+    return result.deletedCount;
+  }
+
+  async getBatch(ids: string[]): Promise<Map<string, T>> {
+    if (ids.length === 0) return new Map();
+
+    const docs = await (await this.getCollection())
+      .find({ _id: { $in: ids } } as Filter<MongoDoc<T>>)
+      .toArray();
+
+    const result = new Map<string, T>();
+    for (const doc of docs) {
+      result.set(String(doc._id), doc.data);
+    }
+    return result;
+  }
+
+  async close(): Promise<void> {
+    // The storage keeps no connection state: the connection belongs to the package
+  }
+
+  async getMetadata(): Promise<StorageMetadata> {
+    const size = await this.size();
+
+    return {
+      type: "custom",
+      size,
+      stats: {
+        collectionName: this.collectionName,
+      },
+    };
+  }
+}

package/src/types.ts

@@ -0,0 +1,337 @@
+/**
+ * TypeScript types for client-mongo procedures
+ */
+
+import { ObjectId } from "mongodb";
+import type { Document, Filter, UpdateFilter } from "mongodb";
+
+// =============================================================================
+// Common Types
+// =============================================================================
+
+/**
+ * Pagination input parameters
+ */
+export interface PaginationInput {
+  /** Page number (1-indexed, default: 1) */
+  page?: number;
+  /** Items per page (default: 20, max: 100) */
+  limit?: number;
+}
+
+/**
+ * Pagination output metadata
+ */
+export interface PaginationOutput {
+  /** Current page number */
+  page: number;
+  /** Items per page */
+  limit: number;
+  /** Total number of items */
+  total: number;
+  /** Total number of pages */
+  totalPages: number;
+  /** Whether there is a next page */
+  hasNext: boolean;
+  /** Whether there is a previous page */
+  hasPrev: boolean;
+}
+
+/**
+ * Sort order for queries
+ */
+export type SortOrder = 1 | -1;
+
+/**
+ * Sort specification
+ */
+export type SortSpec = Record<string, SortOrder>;
+
+// =============================================================================
+// Document Types
+// =============================================================================
+
+/**
+ * Document ID - can be string or ObjectId.
+ * MongoDB supports any type for _id, but string and ObjectId are most common.
+ */
+export type DocumentId = string | ObjectId;
+
+/**
+ * Base document type.
+ * Uses MongoDB's Document type which allows any _id via index signature.
+ */
+export type BaseDocument = Document;
+
+/**
+ * Generic document type - use BaseDocument for proper _id typing
+ */
+export type MongoDocument = BaseDocument;
+
+/**
+ * Document query filter.
+ * Uses Document for compatibility with MongoDB driver methods.
+ */
+export type DocumentQuery = Filter<Document>;
+
+/**
+ * Document update specification
+ */
+export type DocumentUpdate = UpdateFilter<Document>;
+
+/**
+ * How to interpret a string id when building an `_id` filter.
+ *
+ * - `"objectId"` — coerce to an ObjectId (falls back to the raw string when the
+ *   value is not a valid ObjectId).
+ * - `"string"` — match the raw string `_id` only.
+ * - `"auto"` (default) — when the id is a valid ObjectId, match EITHER an
+ *   ObjectId `_id` or the raw string `_id`, so documents stored with a
+ *   string `_id` that happens to be 24-hex (e.g. MongoStorage keys) stay
+ *   reachable. Otherwise match the string.
+ */
+export type IdType = "auto" | "objectId" | "string";
+
+/**
+ * Build an `_id` filter from a string id.
+ *
+ * MongoDB supports any `_id` type at runtime. Previously any string that parsed
+ * as an ObjectId was silently coerced, making 24-hex *string* `_id`s
+ * unreachable. The default `"auto"` mode now queries both forms via `$or` when
+ * the id is ambiguous, and `idType` provides an explicit escape hatch.
+ */
+export function buildIdFilter(id: string, idType: IdType = "auto"): Document {
+  if (idType === "string") {
+    return { _id: id };
+  }
+
+  let objectId: ObjectId | null = null;
+  try {
+    objectId = new ObjectId(id);
+  } catch {
+    objectId = null;
+  }
+
+  if (idType === "objectId") {
+    return { _id: objectId ?? id };
+  }
+
+  // "auto": match both the ObjectId and the raw string when ambiguous.
+  if (objectId) {
+    return { $or: [{ _id: objectId }, { _id: id }] };
+  }
+  return { _id: id };
+}
+
+// =============================================================================
+// Procedure Metadata Types
+// =============================================================================
+
+/**
+ * Base metadata for all procedures
+ */
+export interface BaseMeta extends Record<string, unknown> {
+  /** Override database name */
+  database?: string;
+}
+
+/**
+ * Metadata for collection-scoped procedures
+ */
+export interface CollectionMeta extends BaseMeta {
+  /** Collection name (required) */
+  collection: string;
+}
+
+/**
+ * Type guard to check if metadata has collection
+ */
+export function hasCollection(
+  metadata: Record<string, unknown>
+): metadata is CollectionMeta {
+  return typeof metadata["collection"] === "string";
+}
+
+/**
+ * Type guard to get collection metadata, throws if missing
+ */
+export function requireCollection(
+  metadata: Record<string, unknown>
+): CollectionMeta {
+  if (!hasCollection(metadata)) {
+    throw new Error("collection is required in metadata");
+  }
+  if (metadata.collection.trim().length === 0) {
+    throw new Error("collection must be a non-empty string");
+  }
+  return metadata;
+}
+
+/**
+ * Get base metadata (database override).
+ * BaseMeta extends Record<string, unknown> so this is type-safe.
+ */
+export function getBaseMeta(metadata: Record<string, unknown>): BaseMeta {
+  return metadata;
+}
+
+// =============================================================================
+// Bulk Operation Types
+// =============================================================================
+
+/**
+ * Insert operation for bulk write
+ */
+export interface BulkInsertOne {
+  insertOne: {
+    document: Document;
+  };
+}
+
+/**
+ * Update operation for bulk write
+ */
+export interface BulkUpdateOne {
+  updateOne: {
+    filter: DocumentQuery;
+    update: DocumentUpdate;
+    upsert?: boolean;
+  };
+}
+
+/**
+ * Delete operation for bulk write
+ */
+export interface BulkDeleteOne {
+  deleteOne: {
+    filter: DocumentQuery;
+  };
+}
+
+/**
+ * Bulk operation union type
+ */
+export type BulkOperation = BulkInsertOne | BulkUpdateOne | BulkDeleteOne;
+
+/**
+ * Result of a bulk write operation
+ */
+export interface BulkWriteResult {
+  acknowledged: boolean;
+  insertedCount: number;
+  matchedCount: number;
+  modifiedCount: number;
+  deletedCount: number;
+  upsertedCount: number;
+}
+
+// =============================================================================
+// Index Types
+// =============================================================================
+
+/**
+ * Index key specification
+ */
+export type IndexSpec = Record<string, 1 | -1 | "text" | "2dsphere">;
+
+/**
+ * Index creation options
+ */
+export interface IndexOptions {
+  /** Index name */
+  name?: string | undefined;
+  /** Unique index */
+  unique?: boolean | undefined;
+  /** Sparse index */
+  sparse?: boolean | undefined;
+  /** Build in background */
+  background?: boolean | undefined;
+  /** TTL in seconds */
+  expireAfterSeconds?: number | undefined;
+}
+
+/**
+ * Index information returned by listIndexes
+ */
+export interface IndexInfo {
+  name: string;
+  /** The fields of the index and their kind. The server also gives kinds that IndexSpec does not name ("hashed", "2d"). */
+  key: Record<string, number | string>;
+  unique?: boolean | undefined;
+  sparse?: boolean | undefined;
+}
+
+// =============================================================================
+// Collection Types
+// =============================================================================
+
+/**
+ * Collection creation options
+ */
+export interface CollectionOptions {
+  /** Create a capped collection */
+  capped?: boolean | undefined;
+  /** Max size in bytes (for capped) */
+  size?: number | undefined;
+  /** Max documents (for capped) */
+  max?: number | undefined;
+  /** JSON Schema validator */
+  validator?: Document | undefined;
+}
+
+/**
+ * Collection statistics
+ */
+export interface CollectionStats {
+  /** Number of documents */
+  count: number;
+  /** Size of documents in bytes */
+  size: number;
+  /** Average document size */
+  avgObjSize: number;
+  /** Total storage size */
+  storageSize: number;
+  /** Number of indexes */
+  nindexes: number;
+  /** Total index size */
+  totalIndexSize: number;
+}
+
+// =============================================================================
+// Database Types
+// =============================================================================
+
+/**
+ * Database information
+ */
+export interface DatabaseInfo {
+  /** Database name */
+  name: string;
+  /** Number of collections */
+  collections: number;
+  /** Number of views */
+  views: number;
+  /** Size on disk in bytes */
+  sizeOnDisk: number;
+  /** Whether database is empty */
+  empty: boolean;
+}
+
+// =============================================================================
+// Aggregation Types
+// =============================================================================
+
+/**
+ * Aggregation pipeline stage
+ */
+export type AggregationStage = Document;
+
+/**
+ * Aggregation options
+ */
+export interface AggregationOptions {
+  /** Allow disk use for large operations */
+  allowDiskUse?: boolean | undefined;
+  /** Max execution time in ms */
+  maxTimeMS?: number | undefined;
+}