@bymax-one/nest-queue 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -7,6 +7,110 @@ versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.0.5] — 2026-08-01
+
+Documentation only. `dist/` is byte-identical to `1.0.4` — verified by diffing a
+fresh build against the published tarball — so there is no runtime change.
+
+### Fixed
+
+- **The README's configuration examples did not compile in a strict project.**
+  Eight snippets passed `process.env.REDIS_URL` where a `string` is required:
+
+  ```
+  TS2322: Type 'string | undefined' is not assignable to type 'string'.
+  ```
+
+  `process.env.X` is `string | undefined` under `strict`, so anyone copying the
+  Quick Start into a strict TypeScript project — the configuration this library
+  itself uses and recommends — got a type error out of the box. Now shown with a
+  fallback, which is what the code has to do anyway:
+
+  ```ts
+  connection: {
+    url: process.env.REDIS_URL ?? 'redis://localhost:6379'
+  }
+  ```
+
+  Found by `pnpm check:published`, added in the same release, which compiles the
+  README's own snippets against the built package. Nobody had reported it, and
+  nothing before this would have.
+
+### Added
+
+- **`pnpm check:published`** — a gate that verifies the published surface matches
+  the documentation, before a tag rather than after it. It scaffolds a throwaway
+  consumer, symlinks the package into its own `node_modules` so resolution runs
+  through the `exports` map into `dist/`, and then checks that the README's links
+  resolve, that its TypeScript snippets and the type tests compile against the
+  built package, and that every `v*.*.*` tag has a `## [x.y.z]` CHANGELOG section.
+
+  Each of those exists because its absence let a defect reach npm: the 404 link
+  corrected in `1.0.3`, the exported type that rejected the README's own snippet
+  corrected in `1.0.4`, and a deleted heading that would have turned release notes
+  into the generic fallback.
+
+  It runs in CI, in `release.yml`, and inside `prepublishOnly` — the last one
+  because the first publish of a package is manual by design, which is precisely
+  the path that bypasses the tag workflow.
+
+---
+
+## [1.0.4] — 2026-08-01
+
+### Fixed
+
+- **`BymaxQueueModuleAsyncOptions.useFactory` rejected the factory this library
+  documents.** It was declared `(...args: unknown[]) => …`, and a parameter typed
+  `unknown` accepts no narrower parameter under `strictFunctionTypes`. So the
+  shape shown in the README and in `BymaxQueueModule`'s own `@example`:
+
+  ```ts
+  useFactory: (client: Redis) => ({ connection: { client } })
+  ```
+
+  failed to typecheck **against the exported interface**:
+
+  ```
+  TS2322: Type '(client: Redis) => …' is not assignable to
+          type '(...args: unknown[]) => …'
+  ```
+
+  Scope, precisely: `forRootAsync` is typed by NestJS's `ASYNC_OPTIONS_TYPE`, not
+  by this interface, so passing the object **inline** always compiled. Only a
+  consumer who annotated it — extracting the options into a
+  `const opts: BymaxQueueModuleAsyncOptions = { … }` — hit the error. The
+  interface was stricter than the module it describes.
+
+  It is now declared with **method syntax**. `strictFunctionTypes` makes
+  parameters contravariant for function-typed _properties_ but leaves method
+  parameters bivariant, so the interface accepts a factory that names its
+  injected types. This **widens** what is accepted: every factory that compiled
+  before still does, the variadic `(...args: unknown[])` form included. Nothing
+  needs changing in consumer code.
+
+  Method syntax rather than a looser parameter type, because the factory has to
+  stay **callable**: NestJS invokes it with the values `inject` resolves, and a
+  consumer may call it directly in a unit test. A `never[]` rest parameter would
+  have bought the same assignability and silently cost that —
+  `options.useFactory(client)` fails with `TS2345: Argument of type 'Redis' is
+not assignable to parameter of type 'never'`.
+
+  Pinned by seven cases in `test/types/public-api.test-d.ts` — typed parameter,
+  async, several parameters, zero parameters, the pre-1.0.4 variadic form, and
+  two for callability — where `useFactory` was previously pinned by nothing,
+  which is why this went unnoticed. Red-checked against **both** rejected
+  signatures: the original property form fails the assignability cases, and
+  `never[]` fails the callability ones.
+
+  No runtime change, verified rather than asserted: diffed against the published
+  `1.0.3` tarball, all four emitted runtime files (`server` and `shared`, `.mjs`
+  and `.cjs`) are byte-identical, and only `dist/server/index.d.ts` / `.d.cts`
+  differ. The altered source declares types only, so it produces no Stryker
+  mutants and the 99.06% score stands.
+
+---
+
 ## [1.0.3] — 2026-08-01
 
 Documentation only. `dist/` is byte-identical to `1.0.2` — verified by unpacking
@@ -207,6 +311,9 @@ v6 peer range.
 
 ---
 
+[1.0.5]: https://github.com/bymaxone/nest-queue/releases/tag/v1.0.5
+[1.0.4]: https://github.com/bymaxone/nest-queue/releases/tag/v1.0.4
+[1.0.3]: https://github.com/bymaxone/nest-queue/releases/tag/v1.0.3
 [1.0.2]: https://github.com/bymaxone/nest-queue/releases/tag/v1.0.2
 [1.0.1]: https://github.com/bymaxone/nest-queue/releases/tag/v1.0.1
 [1.0.0]: https://github.com/bymaxone/nest-queue/releases/tag/v1.0.0

package/README.md

@@ -149,7 +149,7 @@ import { BymaxQueueModule } from '@bymax-one/nest-queue'
 @Module({
   imports: [
     BymaxQueueModule.forRoot({
-      connection: { url: process.env.REDIS_URL },
+      connection: { url: process.env.REDIS_URL ?? 'redis://localhost:6379' },
       isGlobal: true,
     }),
   ],
@@ -259,7 +259,7 @@ Mode B lets the library own the Redis connections. Pass either a URL or raw iore
 ```typescript
 // URL form
 BymaxQueueModule.forRoot({
-  connection: { url: process.env.REDIS_URL },
+  connection: { url: process.env.REDIS_URL ?? 'redis://localhost:6379' },
   isGlobal: true,
 })
 
@@ -267,9 +267,9 @@ BymaxQueueModule.forRoot({
 BymaxQueueModule.forRoot({
   connection: {
     options: {
-      host: process.env.REDIS_HOST,
+      host: process.env.REDIS_HOST ?? 'localhost',
       port: Number(process.env.REDIS_PORT),
-      password: process.env.REDIS_PASSWORD,
+      password: process.env.REDIS_PASSWORD ?? undefined,
       tls: {},
     },
   },
@@ -345,7 +345,7 @@ Enable flows in the module options and inject the service:
 
 ```typescript
 BymaxQueueModule.forRoot({
-  connection: { url: process.env.REDIS_URL },
+  connection: { url: process.env.REDIS_URL ?? 'redis://localhost:6379' },
   flows: { enabled: true },
 })
 
@@ -370,7 +370,7 @@ Provide a per-queue snapshot with a configurable TTL cache:
 
 ```typescript
 BymaxQueueModule.forRoot({
-  connection: { url: process.env.REDIS_URL },
+  connection: { url: process.env.REDIS_URL ?? 'redis://localhost:6379' },
   metrics: { enabled: true, cacheTtlMs: 5_000 },
 })
 
@@ -562,7 +562,7 @@ Pass a `bullmq-otel` telemetry instance (optional peer dep) to trace spans from
 import { BullMQOtel } from 'bullmq-otel'
 
 BymaxQueueModule.forRoot({
-  connection: { url: process.env.REDIS_URL },
+  connection: { url: process.env.REDIS_URL ?? 'redis://localhost:6379' },
   telemetry: new BullMQOtel('my-service', tracer),
 })
 ```
@@ -602,7 +602,7 @@ Tune `drainTimeoutMs` when jobs may run longer than 30 s:
 
 ```typescript
 BymaxQueueModule.forRoot({
-  connection: { url: process.env.REDIS_URL },
+  connection: { url: process.env.REDIS_URL ?? 'redis://localhost:6379' },
   shutdown: { drainTimeoutMs: 60_000 },
 })
 ```

package/dist/server/index.d.cts

@@ -97,8 +97,29 @@ interface BymaxQueueOptionsFactory {
 }
 /** Asynchronous configuration mirroring the NestJS async dynamic-module pattern. */
 interface BymaxQueueModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
-    /** Factory returning the module options. */
-    useFactory?: (...args: unknown[]) => Promise<BymaxQueueModuleOptions> | BymaxQueueModuleOptions;
+    /**
+     * Factory returning the module options. Its parameters are whatever `inject`
+     * resolves to, so declare them with the types you expect:
+     *
+     * ```ts
+     * useFactory: (client: Redis) => ({ connection: { client } })
+     * ```
+     *
+     * Declared with **method syntax** on purpose. `strictFunctionTypes` makes
+     * parameters contravariant for function-typed *properties* but leaves method
+     * parameters bivariant, so this accepts a factory that names its injected
+     * types — which a property typed `(...args: unknown[]) => …` rejects, since
+     * `unknown` is assignable from no narrower parameter. That rejection is what
+     * made the form above fail against this interface while compiling when passed
+     * inline to `forRootAsync`.
+     *
+     * Bivariance is the right trade here rather than a looser parameter type:
+     * NestJS resolves these arguments from `inject` at runtime, so no signature
+     * can make them statically safe, and method syntax keeps the factory
+     * **callable** — `options.useFactory(client)` typechecks, which a
+     * `never[]` rest parameter would have broken.
+     */
+    useFactory?(...args: unknown[]): Promise<BymaxQueueModuleOptions> | BymaxQueueModuleOptions;
     /** Class implementing the options factory. */
     useClass?: Type<BymaxQueueOptionsFactory>;
     /** Existing provider implementing the options factory. */

package/dist/server/index.d.ts

@@ -97,8 +97,29 @@ interface BymaxQueueOptionsFactory {
 }
 /** Asynchronous configuration mirroring the NestJS async dynamic-module pattern. */
 interface BymaxQueueModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
-    /** Factory returning the module options. */
-    useFactory?: (...args: unknown[]) => Promise<BymaxQueueModuleOptions> | BymaxQueueModuleOptions;
+    /**
+     * Factory returning the module options. Its parameters are whatever `inject`
+     * resolves to, so declare them with the types you expect:
+     *
+     * ```ts
+     * useFactory: (client: Redis) => ({ connection: { client } })
+     * ```
+     *
+     * Declared with **method syntax** on purpose. `strictFunctionTypes` makes
+     * parameters contravariant for function-typed *properties* but leaves method
+     * parameters bivariant, so this accepts a factory that names its injected
+     * types — which a property typed `(...args: unknown[]) => …` rejects, since
+     * `unknown` is assignable from no narrower parameter. That rejection is what
+     * made the form above fail against this interface while compiling when passed
+     * inline to `forRootAsync`.
+     *
+     * Bivariance is the right trade here rather than a looser parameter type:
+     * NestJS resolves these arguments from `inject` at runtime, so no signature
+     * can make them statically safe, and method syntax keeps the factory
+     * **callable** — `options.useFactory(client)` typechecks, which a
+     * `never[]` rest parameter would have broken.
+     */
+    useFactory?(...args: unknown[]): Promise<BymaxQueueModuleOptions> | BymaxQueueModuleOptions;
     /** Class implementing the options factory. */
     useClass?: Type<BymaxQueueOptionsFactory>;
     /** Existing provider implementing the options factory. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-queue",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "NestJS dynamic module wrapping BullMQ — typed jobs, flows, job schedulers, deduplication, OpenTelemetry, graceful shutdown",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -131,23 +131,24 @@
   },
   "scripts": {
     "build": "pnpm clean && tsup",
+    "check:exports": "attw --pack .",
+    "check:published": "node scripts/check-published-surface.mjs",
+    "clean": "rm -rf dist coverage",
     "lint": "eslint src scripts test",
     "lint:fix": "eslint src scripts test --fix",
-    "test": "jest",
-    "test:cov": "jest --coverage",
-    "test:watch": "jest --watch",
-    "test:e2e": "jest --config jest.e2e.config.ts",
-    "test:all": "pnpm test && pnpm test:e2e",
-    "test:cov:all": "jest --config jest.coverage.config.ts --coverage",
-    "test:types": "tsc --noEmit -p tsconfig.typetest.json",
     "mutation": "stryker run",
-    "mutation:incremental": "stryker run --incremental",
     "mutation:dry-run": "stryker run --dryRunOnly",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.server.json",
+    "mutation:incremental": "stryker run --incremental",
+    "release": "pnpm publish --provenance",
     "size": "node scripts/check-size.mjs",
     "smoke": "node scripts/dogfood-smoke-test.mjs",
-    "check:exports": "attw --pack .",
-    "clean": "rm -rf dist coverage",
-    "release": "pnpm publish --provenance"
+    "test": "jest",
+    "test:all": "pnpm test && pnpm test:e2e",
+    "test:cov": "jest --coverage",
+    "test:cov:all": "jest --config jest.coverage.config.ts --coverage",
+    "test:e2e": "jest --config jest.e2e.config.ts",
+    "test:types": "tsc --noEmit -p tsconfig.typetest.json",
+    "test:watch": "jest --watch",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.server.json"
   }
 }