@twasik4/pocket-service 1.0.2 → 1.0.4

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@twasik4/pocket-service",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
   "peerDependencies": {
-    "@clickhouse/client": "^1.12.1",
+    "@clickhouse/client": "^1.12.1"
+  },
+  "dependencies": {
     "cors": "^2.8.5",
     "express": "^5.1.0",
     "jose": "^6.2.3",
@@ -21,16 +23,8 @@
     "@types/express": "^5.0.3",
     "@types/node": "^24.5.2",
     "@types/winston": "^2.4.4",
-    "cors": "^2.8.5",
-    "express": "^5.1.0",
-    "jose": "^6.2.3",
-    "mongodb": "^6.20.0",
     "mongodb-memory-server": "^11.0.1",
-    "redis": "^5.8.2",
-    "vitest": "^3.2.4",
-    "winston": "^3.17.0",
-    "winston-transport": "^4.9.0",
-    "zod": "^4.1.12"
+    "vitest": "^3.2.4"
   },
   "scripts": {
     "build": "tsup",

package/src/workers/db/clickhouse/index.ts

@@ -7,7 +7,7 @@ export interface ClickhouseTable<TSchema extends Record<string, any>> {
 }
 
 export interface ClickhouseConfig<
-  TTables extends Record<string, ClickhouseTable<any>>
+  TTables extends Record<string, ClickhouseTable<any>>,
 > {
   url: string;
   username?: string;
@@ -16,7 +16,7 @@ export interface ClickhouseConfig<
 }
 
 export function createTypedClickhouse<
-  TTables extends Record<string, ClickhouseTable<any>>
+  TTables extends Record<string, ClickhouseTable<any>>,
 >(config: ClickhouseConfig<TTables>) {
   const client = createClient({
     host: config.url,
@@ -38,7 +38,7 @@ export function createTypedClickhouse<
       const select = async (where?: Filter): Promise<Row[]> => {
         let query = `SELECT * FROM ${table.name}`;
         if (where && Object.keys(where).length > 0) {
-          const conditions = Object.keys(where)
+          const conditions = Object.entries(where)
             .map(([k, value]) => {
               if (typeof value === "string") return `${k} = '${value}'`;
               return `${k} = ${value}`;
@@ -62,11 +62,11 @@ export function createTypedClickhouse<
       };
 
       return [key, { select, insert }];
-    })
+    }),
   ) as {
     [K in keyof TTables]: {
       select(
-        where?: Partial<ReturnType<TTables[K]["schema"]>>
+        where?: Partial<ReturnType<TTables[K]["schema"]>>,
       ): Promise<ReturnType<TTables[K]["schema"]>[]>;
       insert(rows: ReturnType<TTables[K]["schema"]>[]): Promise<void>;
     };

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

@@ -199,12 +199,9 @@ export class CollectionWrapper<T extends Document> {
             },
             {
               $merge: {
-                into: {
-                  db: this.collection.dbName,
-                  col: this.revision.collectionName,
-                  on: "_id",
-                  whenNotMatched: "insert",
-                },
+                into: this.revision.collectionName,
+                on: "_id",
+                whenNotMatched: "insert",
               },
             },
           ])
@@ -218,17 +215,24 @@ export class CollectionWrapper<T extends Document> {
 
   /**
    * Soft delete a document by setting the `deletedAt` field to the current date.
+   * If the schema has a `deletedBy` field, it is set to the provided actor or defaults to `system`.
    * If the schema does not have a `deletedAt` field, it will perform a hard delete.
    * @param filter - The filter to find documents to delete.
+   * @param deletedBy - Optional actor identifier for soft deletes.
    */
-  async delete(filter: Filter<T>): Promise<void> {
+  async delete(filter: Filter<T>, deletedBy?: string): Promise<void> {
     try {
       if (this.hasProperty("deletedAt")) {
         const deletedAt = new Date();
+        const deletedByValue = deletedBy ?? "system";
+        const setFields: Record<string, unknown> = {
+          deletedAt,
+          ...(this.hasProperty("deletedBy")
+            ? { deletedBy: deletedByValue }
+            : {}),
+        };
         const update = {
-          $set: {
-            deletedAt,
-          },
+          $set: setFields,
         } as unknown as UpdateFilter<T>;
         await this.collection.updateMany(filter, update);
         if (this.revision) {
@@ -238,16 +242,13 @@ export class CollectionWrapper<T extends Document> {
                 $match: filter,
               },
               {
-                $set: { _id: new ObjectId(), deletedAt },
+                $set: { _id: new ObjectId(), ...setFields },
               },
               {
                 $merge: {
-                  into: {
-                    db: this.collection.dbName,
-                    col: this.revision.collectionName,
-                    on: "_id",
-                    whenNotMatched: "insert",
-                  },
+                  into: this.revision.collectionName,
+                  on: "_id",
+                  whenNotMatched: "insert",
                 },
               },
             ])

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

@@ -32,6 +32,25 @@ export type MongoIndexSpec = {
   expireAfterSeconds?: number;
 };
 
+export type MongoTimeSeriesSpec = {
+  /**
+   * Name of the date field that MongoDB uses as the event time.
+   */
+  timeField: string;
+  /**
+   * Optional metadata field used to group measurements.
+   */
+  metaField?: string;
+  /**
+   * Optional bucket granularity hint used by MongoDB.
+   */
+  granularity?: "seconds" | "minutes" | "hours";
+  /**
+   * Optional retention in seconds for automatic expiry.
+   */
+  expireAfterSeconds?: number;
+};
+
 export type MongoCollectionMethodContext<TDocument extends Document> = {
   /**
    * The MongoDB client instance
@@ -71,6 +90,10 @@ export type MongoCollectionDefinition<
    * 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[];
+  /**
+   * Optional MongoDB time-series settings. When provided, the collection is created as a time-series collection if it does not already exist.
+   */
+  timeSeries?: MongoTimeSeriesSpec;
 };
 
 export type MongoCollectionsConfig = Record<
@@ -147,6 +170,10 @@ export function defineMongoCollection<
    * Optional array of index specifications to create on this collection.
    */
   indexes?: MongoIndexSpec[];
+  /**
+   * Optional MongoDB time-series settings.
+   */
+  timeSeries?: MongoTimeSeriesSpec;
 }): MongoCollectionDefinition<SchemaOutput<TSchema>, {}>;
 
 /**
@@ -177,6 +204,10 @@ export function defineMongoCollection<
    * Optional array of index specifications to create on this collection.
    */
   indexes?: MongoIndexSpec[];
+  /**
+   * Optional MongoDB time-series settings.
+   */
+  timeSeries?: MongoTimeSeriesSpec;
 }): MongoCollectionDefinition<SchemaOutput<TSchema>, TMethods>;
 
 /**
@@ -207,6 +238,10 @@ export function defineMongoCollection<
    * Optional array of index specifications to create on this collection.
    */
   indexes?: MongoIndexSpec[];
+  /**
+   * Optional MongoDB time-series settings.
+   */
+  timeSeries?: MongoTimeSeriesSpec;
 }): MongoCollectionDefinition<SchemaOutput<TSchema>, TMethods> {
   return {
     name: config.name,
@@ -218,6 +253,7 @@ export function defineMongoCollection<
      */
     methods: config.methods,
     indexes: config.indexes,
+    timeSeries: config.timeSeries,
     /**
      * 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`).
      */
@@ -236,6 +272,7 @@ export function createMongo<TCollections extends MongoCollectionsConfig>(
   const db = client.db(dbName);
 
   const wrapped = {} as InferMongoCollections<TCollections>;
+  const setupFns: Array<() => Promise<void>> = [];
 
   for (const key in config) {
     const def = config[key];
@@ -257,16 +294,78 @@ export function createMongo<TCollections extends MongoCollectionsConfig>(
         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}`,
-          );
-        });
+    setupFns.push(async () => {
+      if (def.timeSeries) {
+        const existingCollection = await db
+          .listCollections({ name: collectionName }, { nameOnly: false })
+          .next();
+
+        if (!existingCollection) {
+          await db.createCollection(collectionName, {
+            timeseries: {
+              timeField: def.timeSeries.timeField,
+              ...(def.timeSeries.metaField
+                ? { metaField: def.timeSeries.metaField }
+                : {}),
+              ...(def.timeSeries.granularity
+                ? { granularity: def.timeSeries.granularity }
+                : {}),
+            },
+            ...(typeof def.timeSeries.expireAfterSeconds === "number"
+              ? { expireAfterSeconds: def.timeSeries.expireAfterSeconds }
+              : {}),
+          });
+        } else {
+          const hasTimeSeriesOptions =
+            existingCollection.type === "timeseries" ||
+            Boolean((existingCollection.options as any)?.timeseries);
+
+          if (!hasTimeSeriesOptions) {
+            throw new Error(
+              `Collection ${collectionName} already exists and is not a time-series collection. Migration is required before enabling timeSeries.`,
+            );
+          }
+
+          const existingTimeSeries = (existingCollection.options as any)
+            ?.timeseries as
+            | {
+                timeField?: string;
+                metaField?: string;
+              }
+            | undefined;
+
+          if (
+            existingTimeSeries?.timeField &&
+            existingTimeSeries.timeField !== def.timeSeries.timeField
+          ) {
+            throw new Error(
+              `Collection ${collectionName} has timeField '${existingTimeSeries.timeField}' but config expects '${def.timeSeries.timeField}'.`,
+            );
+          }
+
+          if (
+            def.timeSeries.metaField &&
+            existingTimeSeries?.metaField &&
+            existingTimeSeries.metaField !== def.timeSeries.metaField
+          ) {
+            throw new Error(
+              `Collection ${collectionName} has metaField '${existingTimeSeries.metaField}' but config expects '${def.timeSeries.metaField}'.`,
+            );
+          }
+        }
       }
-    }
+
+      if (def.indexes && def.indexes.length > 0) {
+        for (const indexSpec of def.indexes) {
+          const { key, ...indexOptions } = indexSpec;
+          await collection.createIndex(key, indexOptions).catch((err) => {
+            console.error(
+              `Failed to create index on ${collectionName}: ${err.message}`,
+            );
+          });
+        }
+      }
+    });
 
     wrapped[key] = Object.assign(
       base,
@@ -274,12 +373,29 @@ export function createMongo<TCollections extends MongoCollectionsConfig>(
     ) as InferMongoCollections<TCollections>[typeof key];
   }
 
+  let setupPromise: Promise<void> | null = null;
+
+  const ensureSetup = async () => {
+    if (!setupPromise) {
+      setupPromise = (async () => {
+        for (const setup of setupFns) {
+          await setup();
+        }
+      })();
+    }
+    return setupPromise;
+  };
+
   return {
     client,
     db,
     collections: wrapped,
     ...wrapped,
     disconnect: async () => client.close(),
-    connect: async () => client.connect(),
+    connect: async () => {
+      await client.connect();
+      await ensureSetup();
+      return client;
+    },
   } as MongoDatabase<TCollections>;
 }

package/src/workers/service.ts

@@ -55,6 +55,7 @@ export class Service<TCollections extends MongoCollectionsConfig = {}> {
     asJson: true,
     customMiddleware: [],
   };
+  private withoutExpressFlag: boolean = false;
 
   private getAuthResolver(): AuthResolver {
     if (this.authResolverOverride) {
@@ -81,6 +82,11 @@ export class Service<TCollections extends MongoCollectionsConfig = {}> {
   }
 
   get api(): Express {
+    if (this.withoutExpressFlag) {
+      throw new Error(
+        "Express server is disabled. Service built without Express.",
+      );
+    }
     if (!this.dependencies.has("expressApp")) {
       this.dependencies.set("expressApp", express());
     }
@@ -326,76 +332,82 @@ export class Service<TCollections extends MongoCollectionsConfig = {}> {
         }
       });
 
-      if (this.expressOptions.asJson) {
-        this.log.info("Configuring Express to parse JSON bodies");
-        this.api.use(express.json());
-      }
+      if (this.withoutExpressFlag) {
+        this.log.warn(
+          "Express server is disabled. Service built without Express.",
+        );
+      } else {
+        if (this.expressOptions.asJson) {
+          this.log.info("Configuring Express to parse JSON bodies");
+          this.api.use(express.json());
+        }
 
-      for (const mw of this.expressOptions.customMiddleware || []) {
-        this.log.info("Adding custom middleware to Express");
-        this.api.use(mw);
-      }
+        for (const mw of this.expressOptions.customMiddleware || []) {
+          this.log.info("Adding custom middleware to Express");
+          this.api.use(mw);
+        }
+
+        if ("corsWhitelist" in this.expressOptions) {
+          this.log.info(
+            "Configuring CORS with whitelist: " +
+              this.expressOptions.corsWhitelist,
+          );
+          this.api.use(
+            cors({
+              origin: this.expressOptions.corsWhitelist,
+              credentials: this.expressOptions.credentials,
+            }),
+          );
+        } else if ("corsFn" in this.expressOptions) {
+          this.log.info("Configuring CORS with function");
+          this.api.use(
+            cors({
+              origin: this.expressOptions.corsFn,
+              credentials: this.expressOptions.credentials,
+            }),
+          );
+        }
 
-      if ("corsWhitelist" in this.expressOptions) {
+        // routers
+        if (!this.expressOptions.omitDefaultRoutes) {
+          this.registerDefaultRoutes();
+        }
+        this.log.info(`Registering ${this.routers.length} routers`);
+        this.routers.forEach(({ base, router }) => {
+          this.api.use(base, router);
+        });
         this.log.info(
-          "Configuring CORS with whitelist: " +
-            this.expressOptions.corsWhitelist,
+          "Routers registered:" +
+            this.routers
+              .map((rt) => {
+                const maxMethodLength = rt.routes
+                  ? Math.max(...rt.routes?.map((r) => r.method.length))
+                  : 0;
+                const maxPathLength = rt.routes
+                  ? Math.max(...rt.routes?.map((r) => r.fullPath.length))
+                  : 0;
+                const maxAuthLength = rt.routes
+                  ? Math.max(...rt.routes?.map((r) => (r.requireAuth ? 6 : 8)))
+                  : 0;
+
+                return `\nRouter ${rt.base}: ${
+                  rt.routes?.length || 0
+                } routes registered.\n${
+                  rt.routes
+                    ?.map(
+                      (r) =>
+                        `\t${("[" + r.method + "]").padEnd(maxMethodLength + 2)} ${(r.requireAuth ? "[Auth]" : "[Public]").padEnd(maxAuthLength)} ${r.fullPath.padEnd(maxPathLength)} | ${r.meta?.description || ""}`,
+                    )
+                    .join("\n") || ""
+                }`;
+              })
+              .join("\n"),
         );
-        this.api.use(
-          cors({
-            origin: this.expressOptions.corsWhitelist,
-            credentials: this.expressOptions.credentials,
-          }),
-        );
-      } else if ("corsFn" in this.expressOptions) {
-        this.log.info("Configuring CORS with function");
-        this.api.use(
-          cors({
-            origin: this.expressOptions.corsFn,
-            credentials: this.expressOptions.credentials,
-          }),
-        );
-      }
 
-      // routers
-      if (!this.expressOptions.omitDefaultRoutes) {
-        this.registerDefaultRoutes();
+        this.api.listen(this.port, () => {
+          this.log.info(`API listening at ${this.fullUrl}`);
+        });
       }
-      this.log.info(`Registering ${this.routers.length} routers`);
-      this.routers.forEach(({ base, router }) => {
-        this.api.use(base, router);
-      });
-      this.log.info(
-        "Routers registered:" +
-          this.routers
-            .map((rt) => {
-              const maxMethodLength = rt.routes
-                ? Math.max(...rt.routes?.map((r) => r.method.length))
-                : 0;
-              const maxPathLength = rt.routes
-                ? Math.max(...rt.routes?.map((r) => r.fullPath.length))
-                : 0;
-              const maxAuthLength = rt.routes
-                ? Math.max(...rt.routes?.map((r) => (r.requireAuth ? 6 : 8)))
-                : 0;
-
-              return `\nRouter ${rt.base}: ${
-                rt.routes?.length || 0
-              } routes registered.\n${
-                rt.routes
-                  ?.map(
-                    (r) =>
-                      `\t${("[" + r.method + "]").padEnd(maxMethodLength + 2)} ${(r.requireAuth ? "[Auth]" : "[Public]").padEnd(maxAuthLength)} ${r.fullPath.padEnd(maxPathLength)} | ${r.meta?.description || ""}`,
-                  )
-                  .join("\n") || ""
-              }`;
-            })
-            .join("\n"),
-      );
-
-      this.api.listen(this.port, () => {
-        this.log.info(`API listening at ${this.fullUrl}`);
-      });
 
       this._status = "running";
       return this;
@@ -852,22 +864,51 @@ export class Service<TCollections extends MongoCollectionsConfig = {}> {
     return this;
   }
 
+  withoutExpress() {
+    this.withoutExpressFlag = true;
+    return this;
+  }
+
   withExpressOptions(options: Partial<ExpressOptions>) {
+    if (this.withoutExpressFlag) {
+      this.log.warn(
+        "Express server is disabled. Express options will not be applied.",
+      );
+      return this;
+    }
     this.expressOptions = { ...this.expressOptions, ...options };
     return this;
   }
 
   withAuthStrategy(strategy: AuthStrategy) {
+    if (this.withoutExpressFlag) {
+      this.log.warn(
+        "Express server is disabled. Auth strategies will not be applied.",
+      );
+      return this;
+    }
     this.authStrategies.push(strategy);
     return this;
   }
 
   withAuthStrategies(strategies: AuthStrategy[]) {
+    if (this.withoutExpressFlag) {
+      this.log.warn(
+        "Express server is disabled. Auth strategies will not be applied.",
+      );
+      return this;
+    }
     this.authStrategies.push(...strategies);
     return this;
   }
 
   withAuthResolver(resolver: AuthResolver) {
+    if (this.withoutExpressFlag) {
+      this.log.warn(
+        "Express server is disabled. Auth resolver will not be applied.",
+      );
+      return this;
+    }
     this.authResolverOverride = resolver;
     return this;
   }
@@ -898,6 +939,12 @@ export class Service<TCollections extends MongoCollectionsConfig = {}> {
     router: Router,
     routes: RouteDefinition<any, any, boolean>[] = [],
   ) {
+    if (this.withoutExpressFlag) {
+      this.log.warn(
+        "Express server is disabled. Routers will not be registered.",
+      );
+      return this;
+    }
     if (base === "/") {
       this.log.warn("Base path '/' is not allowed. Skipping.");
       return this;