@twasik4/pocket-service 1.0.0

package/src/workers/db/mongo/collection.ts

@@ -0,0 +1,292 @@
+import {
+  Collection,
+  Document,
+  Filter,
+  ObjectId,
+  OptionalUnlessRequiredId,
+  UpdateFilter,
+  WithId,
+} from "mongodb";
+
+export type SchemaParser<T extends Document> = {
+  parse: (input: unknown) => T;
+  shape?: unknown;
+  _def?: {
+    shape?: unknown | (() => unknown);
+  };
+};
+
+export class CollectionWrapper<T extends Document> {
+  constructor(
+    private readonly collection: Collection<T>,
+    private readonly schema?: SchemaParser<T>,
+    private readonly revision?: Collection<T>,
+  ) {}
+
+  private parseWrite(doc: unknown): T {
+    if (!this.schema) {
+      return doc as T;
+    }
+    return this.schema.parse(doc);
+  }
+
+  private parseRead(doc: WithId<T>): WithId<T> {
+    if (!this.schema) {
+      return doc;
+    }
+
+    const parsed = this.schema.parse(doc) as T;
+
+    return {
+      ...(parsed as Document),
+      _id: doc._id,
+    } as WithId<T>;
+  }
+
+  private async trackRevision(doc: T) {
+    if (this.revision) {
+      const clone = {
+        ...doc,
+        _id: new ObjectId(),
+      } as OptionalUnlessRequiredId<T>;
+      await this.revision.insertOne(clone);
+    }
+  }
+
+  /**
+   * Get all documents from the collection.
+   * @param filter - The filter to find documents to retrieve. If no filter is provided, it will return all documents in the collection.
+   * @returns
+   */
+  async get(filter: Filter<T> = {}): Promise<WithId<T>[]> {
+    try {
+      if (this.hasProperty("deletedAt")) {
+        // If the schema has a `deletedAt` field, filter out soft-deleted documents
+        filter = { ...filter, deletedAt: { $exists: false } };
+      }
+      const result = await this.collection.find(filter).toArray();
+      return result.map((doc) => this.parseRead(doc));
+    } catch (err) {
+      return [];
+    }
+  }
+
+  /**
+   * Get a single document from the collection.
+   * @param filter - The filter to find the document to retrieve. If no filter is provided, it will return the first document in the collection.
+   * @returns
+   */
+  async getOne(filter: Filter<T> = {}): Promise<WithId<T> | null> {
+    try {
+      if (this.hasProperty("deletedAt")) {
+        // If the schema has a `deletedAt` field, filter out soft-deleted documents
+        filter = { ...filter, deletedAt: { $exists: false } };
+      }
+      const result = await this.collection.findOne(filter);
+      return result ? this.parseRead(result) : null;
+    } catch (err) {
+      return null;
+    }
+  }
+
+  /**
+   * Get all revisions for a document.
+   * @param filter - The filter to find revisions to retrieve. If no filter is provided, it will return all revisions in the revision collection.
+   * @returns An array of revision documents.
+   */
+  async getRevisions(filter: Filter<T> = {}): Promise<WithId<T>[]> {
+    try {
+      if (!this.revision) {
+        return [];
+      }
+      const result = await this.revision
+        .find(filter, { sort: { revision: 1 } })
+        .toArray();
+      return result.map((doc) => this.parseRead(doc as WithId<T>));
+    } catch (err) {
+      return [];
+    }
+  }
+
+  /**
+   * Get the most recent revision for a document.
+   * @returns Revision document or null if no revisions exist or if revision tracking is not enabled.
+   */
+  async getMostRecentRevision(): Promise<WithId<T> | null> {
+    try {
+      if (!this.revision) {
+        return null;
+      }
+      const result = await this.revision
+        .find({}, { sort: { revision: -1 } })
+        .limit(1)
+        .toArray();
+      return result.length > 0 ? this.parseRead(result[0] as WithId<T>) : null;
+    } catch (err) {
+      return null;
+    }
+  }
+
+  /**
+   * Insert a document into the collection.
+   *
+   * If this collection has revision tracking enabled, it will also insert the document into the revision collection.
+   *
+   * @param doc - The document to insert into the collection.
+   */
+  async insert(doc: T): Promise<void> {
+    try {
+      const parsed = this.parseWrite(doc);
+      await this.collection.insertOne(parsed as OptionalUnlessRequiredId<T>);
+      await this.trackRevision(parsed);
+    } catch (err) {
+      throw new Error(`Failed to insert document: ${(err as Error).message}`);
+    }
+  }
+
+  /**
+   * Update multiple documents by filter with a partial document.
+   * @param filter - The filter to find documents to update.
+   * @param update - The partial document to update.
+   */
+  async update(filter: Filter<T>, update: Partial<T>): Promise<void> {
+    try {
+      const existing = await this.collection.find(filter).toArray();
+      if (!existing.length) return;
+
+      await this.collection.updateMany(filter, { $set: update });
+
+      // record updated versions in revisions
+      if (this.revision) {
+        const updatedDocs = existing.map((doc) => ({
+          ...doc,
+          ...update,
+          _id: new ObjectId(),
+        }));
+        await this.revision.insertMany(
+          updatedDocs as OptionalUnlessRequiredId<T>[],
+        );
+      }
+    } catch (err) {
+      throw new Error(`Failed to update documents: ${(err as Error).message}`);
+    }
+  }
+
+  /**
+   * Update a single document by filter with a partial document. This will automatically set the `updatedAt` field to the current date if it exists in the schema, and increment the `revision` field by 1 if it exists in the schema. It will also insert the updated document into the revision collection if revision tracking is enabled.
+   * @param filter - The filter to find the document to update.
+   * @param update - The partial document to update.
+   */
+  async updateOne(filter: Filter<T>, update: Partial<T>): Promise<void> {
+    try {
+      const incomingUpdate = this.hasProperty("updatedAt")
+        ? { ...update, updatedAt: new Date() }
+        : update;
+      const updateDoc = {
+        $set: incomingUpdate,
+        ...(this.revision ? { $inc: { revision: 1 } } : {}),
+      } as UpdateFilter<T>;
+
+      await this.collection.updateOne(filter, updateDoc);
+      if (this.revision) {
+        await this.collection
+          .aggregate([
+            {
+              $match: filter,
+            },
+            {
+              $set: { ...update, _id: new ObjectId() },
+            },
+            {
+              $merge: {
+                into: {
+                  db: this.collection.dbName,
+                  col: this.revision.collectionName,
+                  on: "_id",
+                  whenNotMatched: "insert",
+                },
+              },
+            },
+          ])
+          .toArray();
+      }
+    } catch (err) {
+      console.error("Failed to update document:", err);
+      throw new Error(`Failed to update document: ${(err as Error).message}`);
+    }
+  }
+
+  /**
+   * Soft delete a document by setting the `deletedAt` field to the current date.
+   * If the schema does not have a `deletedAt` field, it will perform a hard delete.
+   * @param filter - The filter to find documents to delete.
+   */
+  async delete(filter: Filter<T>): Promise<void> {
+    try {
+      if (this.hasProperty("deletedAt")) {
+        const deletedAt = new Date();
+        const update = {
+          $set: {
+            deletedAt,
+          },
+        } as unknown as UpdateFilter<T>;
+        await this.collection.updateMany(filter, update);
+        if (this.revision) {
+          await this.collection
+            .aggregate([
+              {
+                $match: filter,
+              },
+              {
+                $set: { _id: new ObjectId(), deletedAt },
+              },
+              {
+                $merge: {
+                  into: {
+                    db: this.collection.dbName,
+                    col: this.revision.collectionName,
+                    on: "_id",
+                    whenNotMatched: "insert",
+                  },
+                },
+              },
+            ])
+            .toArray();
+        }
+      } else {
+        await this.collection.deleteMany(filter);
+      }
+    } catch (err) {
+      throw new Error(`Failed to delete documents: ${(err as Error).message}`);
+    }
+  }
+
+  /**
+   * Checks if the schema has a given property.
+   * @param schema - The Zod schema to check against.
+   * @param property - The property to check for in the schema.
+   * @returns
+   */
+  private hasProperty(property: string): boolean {
+    if (!this.schema) {
+      return false;
+    }
+
+    const schemaLike = this.schema as SchemaParser<T>;
+    const shapeSource =
+      schemaLike.shape ??
+      (typeof schemaLike._def?.shape === "function"
+        ? schemaLike._def.shape()
+        : schemaLike._def?.shape);
+
+    if (
+      shapeSource !== null &&
+      typeof shapeSource === "object" &&
+      !Array.isArray(shapeSource)
+    ) {
+      return property in shapeSource;
+    }
+
+    return false;
+  }
+}

package/src/workers/db/mongo/mongo.ts

@@ -0,0 +1,285 @@
+import { Collection, Db, Document, MongoClient } from "mongodb";
+import { CollectionWrapper, SchemaParser } from "./collection";
+
+type AnyMongoMethod = (...args: any[]) => any;
+
+export type MongoCollectionMethods = Record<string, AnyMongoMethod>;
+
+export type MongoIndexSpec = {
+  /**
+   * Index key specification. Example: { userId: 1 } for ascending, { userId: -1 } for descending
+   */
+  key: Record<string, 1 | -1>;
+  /**
+   * Optional name for the index. If not provided, MongoDB will auto-generate.
+   */
+  name?: string;
+  /**
+   * Whether the index should enforce uniqueness.
+   */
+  unique?: boolean;
+  /**
+   * Whether the index should be sparse (only index documents with the indexed field).
+   */
+  sparse?: boolean;
+  /**
+   * Whether to build the index in the background without blocking other operations.
+   */
+  background?: boolean;
+  /**
+   * The time-to-live (TTL) for documents in the collection, in seconds. Only applicable for TTL indexes.
+   */
+  expireAfterSeconds?: number;
+};
+
+export type MongoCollectionMethodContext<TDocument extends Document> = {
+  /**
+   * The MongoDB client instance
+   */
+  client: MongoClient;
+  /**
+   * The MongoDB database instance
+   */
+  db: Db;
+  /**
+   * The MongoDB collection instance
+   */
+  collection: Collection<TDocument>;
+  /**
+   * The base collection wrapper instance
+   */
+  base: CollectionWrapper<TDocument>;
+};
+
+export type MongoCollectionDefinition<
+  TDocument extends Document = Document,
+  TMethods extends MongoCollectionMethods = {},
+> = {
+  name?: string;
+  /**
+   * Whether to automatically track revisions of documents in this collection. If enabled, every update will insert a copy of the updated document into a separate revision collection, allowing you to keep a history of changes. The revision collection will have the same name as the main collection with `_revisions` appended to it (e.g. `users` -> `users_revisions`).
+   */
+  trackRevisions: boolean;
+  schema: SchemaParser<TDocument>;
+  /**
+   * Custom methods to add to the collection wrapper. These methods receive a context object with the MongoDB client, database, collection, and base wrapper instance, allowing you to build complex queries and operations while still benefiting from the schema validation and soft delete functionality provided by the base wrapper.
+   * @param ctx
+   * @returns
+   */
+  methods?: (ctx: MongoCollectionMethodContext<TDocument>) => TMethods;
+  /**
+   * Optional array of index specifications to create on this collection. Indexes are created idempotently on service startup, so duplicate indexes are safely ignored.
+   */
+  indexes?: MongoIndexSpec[];
+};
+
+export type MongoCollectionsConfig = Record<
+  string,
+  MongoCollectionDefinition<any, MongoCollectionMethods>
+>;
+
+type InferDocument<TDefinition> = TDefinition extends {
+  schema: SchemaParser<infer TDocument>;
+}
+  ? TDocument
+  : Document;
+
+type NormalizeDocument<TDocument> = TDocument extends Document
+  ? TDocument
+  : Document;
+
+type InferMethods<TDefinition> = TDefinition extends {
+  methods: (...args: any[]) => infer TMethods;
+}
+  ? TMethods
+  : TDefinition extends {
+        methods?: (...args: any[]) => infer TMethods;
+      }
+    ? TMethods extends undefined
+      ? {}
+      : TMethods
+    : {};
+
+export type MongoBoundCollection<
+  TDocument extends Document,
+  TMethods extends MongoCollectionMethods = {},
+> = CollectionWrapper<TDocument> & TMethods;
+
+export type InferMongoCollections<TCollections extends MongoCollectionsConfig> =
+  {
+    [K in keyof TCollections]: MongoBoundCollection<
+      NormalizeDocument<InferDocument<TCollections[K]>>,
+      InferMethods<TCollections[K]>
+    >;
+  };
+
+export type MongoDatabase<TCollections extends MongoCollectionsConfig> = {
+  client: MongoClient;
+  db: Db;
+  collections: InferMongoCollections<TCollections>;
+  disconnect: () => Promise<void>;
+  connect: () => Promise<MongoClient>;
+} & InferMongoCollections<TCollections>;
+
+type SchemaOutput<TSchema> = TSchema extends {
+  parse: (input: unknown) => infer TOutput;
+}
+  ? NormalizeDocument<TOutput>
+  : Document;
+
+/**
+ * Define a MongoDB collection with an associated Zod schema for validation and optional custom methods. The returned collection definition can then be used to create a MongoDatabase instance, which will automatically wrap the collection with the provided schema validation and methods.
+ * @param config The configuration object for the MongoDB collection, including the schema and optional custom methods.
+ */
+export function defineMongoCollection<
+  TSchema extends SchemaParser<any>,
+>(config: {
+  /**
+   * Optional name for the collection. If not provided, the key used in the collections config will be used as the collection name. This allows you to have more control over the actual collection names in the database, while still using descriptive keys in your code.
+   */
+  name?: string;
+  /**
+   * Zod schema for validating documents in the collection. The schema will be used to parse and validate documents returned from the database, ensuring that they conform to the expected structure and types. If a document does not match the schema, an error will be thrown.
+   */
+  schema: TSchema;
+  methods?: undefined;
+  /**
+   * Optional array of index specifications to create on this collection.
+   */
+  indexes?: MongoIndexSpec[];
+}): MongoCollectionDefinition<SchemaOutput<TSchema>, {}>;
+
+/**
+ * Define a MongoDB collection with an associated Zod schema for validation and optional custom methods. The returned collection definition can then be used to create a MongoDatabase instance, which will automatically wrap the collection with the provided schema validation and methods.
+ * @param config The configuration object for the MongoDB collection, including the schema and optional custom methods.
+ */
+export function defineMongoCollection<
+  TSchema extends SchemaParser<any>,
+  TMethods extends MongoCollectionMethods,
+>(config: {
+  /**
+   * Optional name for the collection. If not provided, the key used in the collections config will be used as the collection name. This allows you to have more control over the actual collection names in the database, while still using descriptive keys in your code.
+   */
+  name?: string;
+  /**
+   * Zod schema for validating documents in the collection. The schema will be used to parse and validate documents returned from the database, ensuring that they conform to the expected structure and types. If a document does not match the schema, an error will be thrown.
+   */
+  schema: TSchema;
+  /**
+   * Optional custom methods for the collection. These methods will be added to the collection instance and can be used to implement custom queries or operations.
+   * @param ctx The context object containing the MongoDB client, database, collection, and base collection wrapper.
+   * @returns An object containing the custom methods to be added to the collection instance.
+   */
+  methods: (
+    ctx: MongoCollectionMethodContext<SchemaOutput<TSchema>>,
+  ) => TMethods;
+  /**
+   * Optional array of index specifications to create on this collection.
+   */
+  indexes?: MongoIndexSpec[];
+}): MongoCollectionDefinition<SchemaOutput<TSchema>, TMethods>;
+
+/**
+ * Define a MongoDB collection with an associated Zod schema for validation and optional custom methods. The returned collection definition can then be used to create a MongoDatabase instance, which will automatically wrap the collection with the provided schema validation and methods.
+ * @param config The configuration object for the MongoDB collection, including the schema and optional custom methods.
+ */
+export function defineMongoCollection<
+  TSchema extends SchemaParser<any>,
+  TMethods extends MongoCollectionMethods = {},
+>(config: {
+  /**
+   * Optional name for the collection. If not provided, the key used in the collections config will be used as the collection name. This allows you to have more control over the actual collection names in the database, while still using descriptive keys in your code.
+   */
+  name?: string;
+  /**
+   * Zod schema for validating documents in the collection. The schema will be used to parse and validate documents returned from the database, ensuring that they conform to the expected structure and types. If a document does not match the schema, an error will be thrown.
+   */
+  schema: TSchema;
+  /**
+   * Optional custom methods for the collection. These methods will be added to the collection instance and can be used to implement custom queries or operations.
+   * @param ctx The context object containing the MongoDB client, database, collection, and base collection wrapper.
+   * @returns An object containing the custom methods to be added to the collection instance.
+   */
+  methods?: (
+    ctx: MongoCollectionMethodContext<SchemaOutput<TSchema>>,
+  ) => TMethods;
+  /**
+   * Optional array of index specifications to create on this collection.
+   */
+  indexes?: MongoIndexSpec[];
+}): MongoCollectionDefinition<SchemaOutput<TSchema>, TMethods> {
+  return {
+    name: config.name,
+    schema: config.schema,
+    /**
+     * Optional custom methods for the collection. These methods will be added to the collection instance and can be used to implement custom queries or operations.
+     * @param ctx The context object containing the MongoDB client, database, collection, and base collection wrapper.
+     * @returns An object containing the custom methods to be added to the collection instance.
+     */
+    methods: config.methods,
+    indexes: config.indexes,
+    /**
+     * Whether to automatically track revisions of documents in this collection. If enabled, every update will insert a copy of the updated document into a separate revision collection, allowing you to keep a history of changes. The revision collection will have the same name as the main collection with `_revisions` appended to it (e.g. `users` -> `users_revisions`).
+     */
+    trackRevisions: false,
+  } as MongoCollectionDefinition<SchemaOutput<TSchema>, TMethods>;
+}
+
+export function createMongo<TCollections extends MongoCollectionsConfig>(
+  dbName: string,
+  config: TCollections,
+  options: { uri?: string } = {},
+): MongoDatabase<TCollections> {
+  const client = new MongoClient(
+    options.uri || process.env.MONGO_URI || "mongodb://mongo:27017",
+  );
+  const db = client.db(dbName);
+
+  const wrapped = {} as InferMongoCollections<TCollections>;
+
+  for (const key in config) {
+    const def = config[key];
+    const collectionName = def.name || key;
+    const collection = db.collection(collectionName);
+    const revisionCollection = def.trackRevisions
+      ? db.collection(`${collectionName}_revisions`)
+      : undefined;
+    const base = new CollectionWrapper(
+      collection as Collection<any>,
+      def.schema,
+      revisionCollection,
+    );
+    const methods =
+      def.methods?.({
+        client,
+        db,
+        collection: collection as Collection<any>,
+        base,
+      }) || {};
+
+    if (def.indexes && def.indexes.length > 0) {
+      for (const indexSpec of def.indexes) {
+        const { key, ...options } = indexSpec;
+        collection.createIndex(key, options).catch((err) => {
+          console.error(
+            `Failed to create index on ${collectionName}: ${err.message}`,
+          );
+        });
+      }
+    }
+
+    wrapped[key] = Object.assign(
+      base,
+      methods,
+    ) as InferMongoCollections<TCollections>[typeof key];
+  }
+
+  return {
+    client,
+    db,
+    collections: wrapped,
+    ...wrapped,
+    disconnect: async () => client.close(),
+    connect: async () => client.connect(),
+  } as MongoDatabase<TCollections>;
+}