Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AtomicQueuesModule
✓ import { AtomicQueuesModule } from 'atomic-queues'
✗ const AtomicQueuesModule = require('atomic-queues')
ESM-only since v3; CommonJS require() will fail.
VirtualActor
✓ import { VirtualActor } from 'atomic-queues'
✗ import VirtualActor from 'atomic-queues'
This is a named export, not default.
AtomicQueuesModule.forRoot
✓ import { AtomicQueuesModule } from 'atomic-queues'; @Module({ imports: [AtomicQueuesModule.forRoot({...})] })
forRoot returns a dynamic module; must be called in root module.
AtomicQueuesModule.forFeature
✓ import { AtomicQueuesModule } from 'atomic-queues'; @Module({ imports: [AtomicQueuesModule.forFeature()] })
forFeature is used in feature modules to register handlers.
Registers AtomicQueuesModule with Redis config in root, then uses @VirtualActor decorator on a CQRS command handler to ensure per-entity sequential processing.
import { Module } from '@nestjs/common';
import { AtomicQueuesModule } from 'atomic-queues';
import { YourHandler } from './your.handler';
@Module({
imports: [
AtomicQueuesModule.forRoot({
redis: {
host: process.env.REDIS_HOST ?? 'localhost',
port: parseInt(process.env.REDIS_PORT ?? '6379', 10),
password: process.env.REDIS_PASSWORD ?? undefined
},
worker: {
concurrency: 10,
idleTimeout: 30000,
maxRetries: 3
},
cluster: {
enabled: process.env.CLUSTER === 'true',
nodeId: process.env.NODE_ID ?? 'node-1',
heartbeatInterval: 5000
}
}),
AtomicQueuesModule.forFeature({
handlers: [YourHandler]
})
]
})
export class AppModule {}
// your.handler.ts
import { ICommandHandler, CommandHandler } from '@nestjs/cqrs';
import { VirtualActor } from 'atomic-queues';
export class TransferFundsCommand {
constructor(public readonly accountId: string, public readonly amount: number) {}
}
@CommandHandler(TransferFundsCommand)
export class TransferFundsHandler implements ICommandHandler<TransferFundsCommand> {
@VirtualActor()
async execute(command: TransferFundsCommand): Promise<void> {
// This method is automatically serialized per accountId
const { accountId, amount } = command;
// Web3 call or database operation that must be serialized
await someCriticalOperation(accountId, amount);
}
}
Errors
Common errors & fixes
Cannot find module 'atomic-queues' or its corresponding type declarations.
Missing npm install or incorrect import path.
fixnpm install atomic-queues ioredis
The CJS build of this library may not support dynamic import.
Trying to use CommonJS require() with v3.
fixUse import statements or set type: module in package.json.
TypeError: Cannot read properties of undefined (reading 'forRoot')
AtomicQueuesModule is not imported correctly or is null.
fixEnsure import is: import { AtomicQueuesModule } from 'atomic-queues'; Nest can't resolve dependencies of the AtomicQueuesModule. Please make sure that the argument RedisClient at index [0] is available.
Missing Redis provider configuration.
fixEnsure Redis connection options are passed to forRoot({ redis: {...} }). Audit
Dependencies
@nestjs/commonrequiredCore NestJS decorators and modules required
@nestjs/corerequiredNestJS application context and DI container
@nestjs/cqrsrequiredCommand/query handling for message dispatching
ioredisrequiredRedis client for queue persistence and worker coordination
reflect-metadatarequiredRequired by NestJS for decorator metadata
rxjsrequiredReactive streams for message processing
zodoptionalSchema validation for CLI and message payloads
@grpc/grpc-jsoptionalRequired for cluster mode gRPC transport
@grpc/proto-loaderoptionalRequired for cluster mode protobuf definitions