From 5d28f1afd9b55df767b997604a14ef5e41996ce1 Mon Sep 17 00:00:00 2001 From: Giovani Guizzo Date: Mon, 18 Aug 2025 19:45:12 -0300 Subject: [PATCH 1/7] feat: Add example Knex configuration for PostgreSQL backend in documentation --- packages/docs/engine/backends.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/packages/docs/engine/backends.md b/packages/docs/engine/backends.md index ad14fd80..a41708b0 100644 --- a/packages/docs/engine/backends.md +++ b/packages/docs/engine/backends.md @@ -49,6 +49,34 @@ await Sidequest.start({ }); ``` +**Using Knex Configuration Object:** + +```typescript +import { Sidequest } from "sidequest"; + +await Sidequest.start({ + backend: { + driver: "@sidequest/postgres-backend", + config: { + connection: { + host: "localhost", + port: 5432, + user: "username", + password: "password", + database: "sidequest", + }, + pool: { + min: 2, + max: 10, + acquireTimeoutMillis: 60000, + idleTimeoutMillis: 600000, + }, + searchPath: ["sidequest", "public"], + }, + }, +}); +``` + **Advantages:** - **Excellent concurrency**: Advanced locking mechanisms prevent job conflicts From 640c2710e3f72979f95577973a5625146b430ac7 Mon Sep 17 00:00:00 2001 From: Giovani Guizzo Date: Mon, 18 Aug 2025 20:42:28 -0300 Subject: [PATCH 2/7] feat: Add backend typing --- packages/sidequest/package.json | 1 + .../sidequest/src/operations/sidequest.ts | 58 ++++++++++++++++++- yarn.lock | 1 + 3 files changed, 57 insertions(+), 3 deletions(-) diff --git a/packages/sidequest/package.json b/packages/sidequest/package.json index b2e7a034..b6260676 100644 --- a/packages/sidequest/package.json +++ b/packages/sidequest/package.json @@ -44,6 +44,7 @@ "test:ci": "npx vitest run" }, "dependencies": { + "@sidequest/backend": "workspace:*", "@sidequest/core": "workspace:*", "@sidequest/dashboard": "workspace:*", "@sidequest/engine": "workspace:*" diff --git a/packages/sidequest/src/operations/sidequest.ts b/packages/sidequest/src/operations/sidequest.ts index 9413983b..aceb7df8 100644 --- a/packages/sidequest/src/operations/sidequest.ts +++ b/packages/sidequest/src/operations/sidequest.ts @@ -1,10 +1,62 @@ +import { SQLDriverConfig } from "@sidequest/backend"; import { JobClassType, logger } from "@sidequest/core"; import { DashboardConfig, SidequestDashboard } from "@sidequest/dashboard"; import { Engine, EngineConfig } from "@sidequest/engine"; import { JobOperations } from "./job"; import { QueueOperations } from "./queue"; -export type SidequestConfig = EngineConfig & { +/** + * Known backend driver identifiers + */ +type KnownSQLDrivers = "@sidequest/postgres-backend" | "@sidequest/mysql-backend" | "@sidequest/sqlite-backend"; + +/** + * Known MongoDB driver identifier + */ +type KnownMongoDriver = "@sidequest/mongo-backend"; + +/** + * All known backend driver identifiers + */ +type KnownDrivers = KnownSQLDrivers | KnownMongoDriver; + +/** + * Strongly typed backend configuration that automatically infers config type based on driver + */ +export type StronglyTypedBackendConfig = TDriver extends KnownSQLDrivers + ? { + /** SQL backend driver identifier */ + driver: TDriver; + /** Database configuration - can be a connection string or detailed config object */ + config: string | SQLDriverConfig; + } + : TDriver extends KnownMongoDriver + ? { + /** MongoDB backend driver identifier */ + driver: TDriver; + /** MongoDB connection string */ + config: string; + } + : { + /** Custom backend driver identifier */ + driver: TDriver; + /** Custom configuration - type is unknown for flexibility */ + config: unknown; + }; + +/** + * Sidequest engine configuration with strongly typed backend + */ +export type SidequestEngineConfig = Omit & { + /** Backend configuration with driver-specific typing */ + backend: StronglyTypedBackendConfig; +}; + +/** + * Complete Sidequest configuration + */ +export type SidequestConfig = SidequestEngineConfig & { + /** Optional dashboard configuration */ dashboard?: Omit; }; @@ -78,7 +130,7 @@ export class Sidequest { * }); * ``` */ - static async configure(config?: EngineConfig) { + static async configure(config?: SidequestEngineConfig) { const _config = await this.engine.configure(config); const backend = this.engine.getBackend(); this.job.setBackend(backend); @@ -105,7 +157,7 @@ export class Sidequest { * }); * ``` */ - static async start(config?: SidequestConfig) { + static async start(config?: SidequestConfig) { try { const engineConfig = await this.configure(config); diff --git a/yarn.lock b/yarn.lock index 1a0bb26f..8def44b7 100644 --- a/yarn.lock +++ b/yarn.lock @@ -11421,6 +11421,7 @@ __metadata: version: 0.0.0-use.local resolution: "sidequest@workspace:packages/sidequest" dependencies: + "@sidequest/backend": "workspace:*" "@sidequest/core": "workspace:*" "@sidequest/dashboard": "workspace:*" "@sidequest/engine": "workspace:*" From 9286d1c6795e8a484e971cd86788c16dfcfe7a50 Mon Sep 17 00:00:00 2001 From: Giovani Guizzo Date: Mon, 18 Aug 2025 20:45:26 -0300 Subject: [PATCH 3/7] feat: Simplify PostgreSQL connection configuration in documentation --- packages/docs/engine/backends.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/packages/docs/engine/backends.md b/packages/docs/engine/backends.md index a41708b0..4e4985a7 100644 --- a/packages/docs/engine/backends.md +++ b/packages/docs/engine/backends.md @@ -58,18 +58,10 @@ await Sidequest.start({ backend: { driver: "@sidequest/postgres-backend", config: { - connection: { - host: "localhost", - port: 5432, - user: "username", - password: "password", - database: "sidequest", - }, + connection: "postgres://user:password@localhost:5432/mydb", pool: { min: 2, max: 10, - acquireTimeoutMillis: 60000, - idleTimeoutMillis: 600000, }, searchPath: ["sidequest", "public"], }, From fa414b38508c1c7893d349f3f28ff87b6622ff45 Mon Sep 17 00:00:00 2001 From: Giovani Guizzo Date: Mon, 18 Aug 2025 20:49:15 -0300 Subject: [PATCH 4/7] feat: move types to a specific file --- packages/sidequest/src/operations/index.ts | 1 + .../sidequest/src/operations/sidequest.ts | 61 +------------------ packages/sidequest/src/operations/types.ts | 58 ++++++++++++++++++ 3 files changed, 62 insertions(+), 58 deletions(-) create mode 100644 packages/sidequest/src/operations/types.ts diff --git a/packages/sidequest/src/operations/index.ts b/packages/sidequest/src/operations/index.ts index dd233b8e..eb7613c3 100644 --- a/packages/sidequest/src/operations/index.ts +++ b/packages/sidequest/src/operations/index.ts @@ -1,3 +1,4 @@ export * from "./job"; export * from "./queue"; export * from "./sidequest"; +export * from "./types"; diff --git a/packages/sidequest/src/operations/sidequest.ts b/packages/sidequest/src/operations/sidequest.ts index aceb7df8..179d4cb5 100644 --- a/packages/sidequest/src/operations/sidequest.ts +++ b/packages/sidequest/src/operations/sidequest.ts @@ -1,64 +1,9 @@ -import { SQLDriverConfig } from "@sidequest/backend"; import { JobClassType, logger } from "@sidequest/core"; -import { DashboardConfig, SidequestDashboard } from "@sidequest/dashboard"; -import { Engine, EngineConfig } from "@sidequest/engine"; +import { SidequestDashboard } from "@sidequest/dashboard"; +import { Engine } from "@sidequest/engine"; import { JobOperations } from "./job"; import { QueueOperations } from "./queue"; - -/** - * Known backend driver identifiers - */ -type KnownSQLDrivers = "@sidequest/postgres-backend" | "@sidequest/mysql-backend" | "@sidequest/sqlite-backend"; - -/** - * Known MongoDB driver identifier - */ -type KnownMongoDriver = "@sidequest/mongo-backend"; - -/** - * All known backend driver identifiers - */ -type KnownDrivers = KnownSQLDrivers | KnownMongoDriver; - -/** - * Strongly typed backend configuration that automatically infers config type based on driver - */ -export type StronglyTypedBackendConfig = TDriver extends KnownSQLDrivers - ? { - /** SQL backend driver identifier */ - driver: TDriver; - /** Database configuration - can be a connection string or detailed config object */ - config: string | SQLDriverConfig; - } - : TDriver extends KnownMongoDriver - ? { - /** MongoDB backend driver identifier */ - driver: TDriver; - /** MongoDB connection string */ - config: string; - } - : { - /** Custom backend driver identifier */ - driver: TDriver; - /** Custom configuration - type is unknown for flexibility */ - config: unknown; - }; - -/** - * Sidequest engine configuration with strongly typed backend - */ -export type SidequestEngineConfig = Omit & { - /** Backend configuration with driver-specific typing */ - backend: StronglyTypedBackendConfig; -}; - -/** - * Complete Sidequest configuration - */ -export type SidequestConfig = SidequestEngineConfig & { - /** Optional dashboard configuration */ - dashboard?: Omit; -}; +import { KnownDrivers, SidequestConfig, SidequestEngineConfig } from "./types"; /** * Main entry point for the Sidequest job processing system. diff --git a/packages/sidequest/src/operations/types.ts b/packages/sidequest/src/operations/types.ts new file mode 100644 index 00000000..b36d16a2 --- /dev/null +++ b/packages/sidequest/src/operations/types.ts @@ -0,0 +1,58 @@ +import { SQLDriverConfig } from "@sidequest/backend"; +import { DashboardConfig } from "@sidequest/dashboard"; +import { EngineConfig } from "@sidequest/engine"; + +/** + * Known backend driver identifiers + */ +export type KnownSQLDrivers = "@sidequest/postgres-backend" | "@sidequest/mysql-backend" | "@sidequest/sqlite-backend"; + +/** + * Known MongoDB driver identifier + */ +export type KnownMongoDriver = "@sidequest/mongo-backend"; + +/** + * All known backend driver identifiers + */ +export type KnownDrivers = KnownSQLDrivers | KnownMongoDriver; + +/** + * Strongly typed backend configuration that automatically infers config type based on driver + */ +export type StronglyTypedBackendConfig = TDriver extends KnownSQLDrivers + ? { + /** SQL backend driver identifier */ + driver: TDriver; + /** Database configuration - can be a connection string or detailed config object */ + config: string | SQLDriverConfig; + } + : TDriver extends KnownMongoDriver + ? { + /** MongoDB backend driver identifier */ + driver: TDriver; + /** MongoDB connection string */ + config: string; + } + : { + /** Custom backend driver identifier */ + driver: TDriver; + /** Custom configuration - type is unknown for flexibility */ + config: unknown; + }; + +/** + * Sidequest engine configuration with strongly typed backend + */ +export type SidequestEngineConfig = Omit & { + /** Backend configuration with driver-specific typing */ + backend: StronglyTypedBackendConfig; +}; + +/** + * Complete Sidequest configuration + */ +export type SidequestConfig = SidequestEngineConfig & { + /** Optional dashboard configuration */ + dashboard?: Omit; +}; From 09a6e9d286b2e11cfe27b205f524c9499dcf3afa Mon Sep 17 00:00:00 2001 From: Giovani Guizzo Date: Mon, 18 Aug 2025 21:03:18 -0300 Subject: [PATCH 5/7] docs: add Node.js version requirement and Bun compatibility note --- README.md | 2 ++ packages/docs/installation.md | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/README.md b/README.md index 7e5f8750..2f7e5360 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,8 @@ npm install sidequest yarn add sidequest ``` +Make sure you are using Node.js >= 22.6.0. Also, [Sidequest does not run with Bun yet](https://github.com/sidequestjs/sidequest/issues/72). + To keep the application minimal, the main package does _not_ include the backend drivers. Thus you need to install only the driver you will use: **PostgreSQL (recommended)** diff --git a/packages/docs/installation.md b/packages/docs/installation.md index a6bfdeb8..3c51708e 100644 --- a/packages/docs/installation.md +++ b/packages/docs/installation.md @@ -8,6 +8,10 @@ description: Installation instructions for Sidequest.js To get started with Sidequest.js, you need to install the main package along with the backend driver of your choice. Below are the installation instructions for different package managers. +::: warning +Make sure you are using Node.js >= 22.6.0. Also, [Sidequest does not run with Bun](https://github.com/sidequestjs/sidequest/issues/72). +::: + ## Main Package (Required) To get started with Sidequest, first install the main package: From 855f47cf0182a7d3c1697fe5d41c05d1c1d31936 Mon Sep 17 00:00:00 2001 From: Giovani Guizzo Date: Mon, 18 Aug 2025 21:04:38 -0300 Subject: [PATCH 6/7] refactor: move SidequestConfig import to types file --- packages/sidequest/src/operations/sidequest.test.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/sidequest/src/operations/sidequest.test.ts b/packages/sidequest/src/operations/sidequest.test.ts index 3a8c7f34..13bf6fcb 100644 --- a/packages/sidequest/src/operations/sidequest.test.ts +++ b/packages/sidequest/src/operations/sidequest.test.ts @@ -2,7 +2,8 @@ import { Job } from "@sidequest/core"; import { NonNullableEngineConfig } from "@sidequest/engine"; import { JobOperations } from "./job"; import { QueueOperations } from "./queue"; -import { Sidequest, SidequestConfig } from "./sidequest"; +import { Sidequest } from "./sidequest"; +import { SidequestConfig } from "./types"; // Mock dependencies const mockSidequestDashboard = vi.hoisted(() => ({ From 0c36c4175052ab99c333b28b3f5723cd051610a7 Mon Sep 17 00:00:00 2001 From: Giovani Guizzo Date: Mon, 18 Aug 2025 21:12:30 -0300 Subject: [PATCH 7/7] feat: add countJobsByQueues method to MyCustomBackend class --- packages/docs/engine/backends.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/docs/engine/backends.md b/packages/docs/engine/backends.md index 4e4985a7..f9d1749b 100644 --- a/packages/docs/engine/backends.md +++ b/packages/docs/engine/backends.md @@ -370,6 +370,10 @@ export class MyCustomBackend implements Backend { // Count jobs by state } + async countJobsByQueues(): Promise>; { + // Count jobs by queue + } + async countJobsOverTime(timeRange: string): Promise<({ timestamp: Date } & JobCounts)[]> { // Count jobs over time for analytics }