@navios/schedule 0.3.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@navios/schedule",
+  "version": "0.3.0",
+  "author": {
+    "name": "Oleksandr Hanzha",
+    "email": "alex@granted.name"
+  },
+  "repository": {
+    "directory": "packages/schedule",
+    "type": "git",
+    "url": "https://github.com/Arilas/navios.git"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@navios/core": "^0.3.0",
+    "zod": "^3.23.8"
+  },
+  "typings": "./lib/index.d.mts",
+  "main": "./lib/index.js",
+  "module": "./lib/index.mjs",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/index.d.mts",
+        "default": "./lib/index.mjs"
+      },
+      "require": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      }
+    }
+  },
+  "devDependencies": {
+    "@navios/core": "^0.3.0",
+    "typescript": "^5.8.3",
+    "zod": "^3.24.4"
+  },
+  "dependencies": {
+    "cron": "^4.3.0"
+  }
+}

package/project.json

@@ -0,0 +1,53 @@
+{
+  "name": "@navios/schedule",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/schedule/src",
+  "prefix": "schedule",
+  "tags": [],
+  "projectType": "library",
+  "targets": {
+    "check": {
+      "executor": "nx:run-commands",
+      "outputs": ["{projectRoot}/dist"],
+      "inputs": ["^projectSources", "projectSources"],
+      "options": {
+        "command": ["tsc -b"],
+        "cwd": "packages/schedule"
+      }
+    },
+    "test:ci": {
+      "executor": "nx:run-commands",
+      "inputs": ["^projectSources", "project"],
+      "options": {
+        "command": "vitest run",
+        "cwd": "packages/schedule"
+      }
+    },
+    "build": {
+      "executor": "nx:run-commands",
+      "inputs": ["projectSources"],
+      "outputs": ["{projectRoot}/lib"],
+      "dependsOn": ["check", "test:ci"],
+      "options": {
+        "command": "tsup",
+        "cwd": "packages/schedule"
+      }
+    },
+    "publish": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build"],
+      "options": {
+        "command": "yarn npm publish --access public",
+        "cwd": "packages/schedule"
+      }
+    },
+    "publish:next": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build"],
+      "options": {
+        "command": "yarn npm publish --access public --tag next",
+        "cwd": "packages/schedule"
+      }
+    }
+  }
+}

package/src/__tests__/schedule.spec.mts

@@ -0,0 +1,167 @@
+import { inject, Injectable } from '@navios/core'
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { Cron, Schedulable } from '../decorators/index.mjs'
+import { SchedulerService } from '../scheduler.service.mjs'
+
+describe('Schedule Module', () => {
+  let schedulerService: SchedulerService
+
+  beforeEach(async () => {
+    vi.useFakeTimers()
+    schedulerService = await inject(SchedulerService)
+  })
+
+  afterEach(() => {
+    schedulerService.stopAll()
+    vi.useRealTimers()
+    vi.clearAllMocks()
+  })
+
+  it('should register a schedulable service', () => {
+    @Schedulable()
+    class TestService {
+      @Cron('*/1 * * * * *')
+      async testJob() {}
+    }
+
+    expect(() => schedulerService.register(TestService)).not.toThrow()
+    const job = schedulerService.getJob(TestService, 'testJob')
+    expect(job).toBeDefined()
+    expect(job?.isActive).toBe(true)
+  })
+
+  it('should throw an error when registering a non-schedulable service', () => {
+    @Injectable()
+    class NonSchedulableService {
+      async testJob() {}
+    }
+
+    expect(() => schedulerService.register(NonSchedulableService)).toThrow()
+  })
+
+  it('should execute a job at the scheduled time', async () => {
+    const mockJob = vi.fn()
+
+    @Schedulable()
+    class TestService {
+      @Cron('*/1 * * * * *')
+      async testJob() {
+        mockJob()
+      }
+    }
+
+    schedulerService.register(TestService)
+    expect(mockJob).not.toHaveBeenCalled()
+
+    // Advance time by 1 second to trigger the job
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(mockJob).toHaveBeenCalledTimes(1)
+
+    // Advance time by another second to trigger again
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(mockJob).toHaveBeenCalledTimes(2)
+  })
+
+  it('should not execute jobs when they are stopped', async () => {
+    const mockJob = vi.fn()
+
+    @Schedulable()
+    class TestService {
+      @Cron('*/1 * * * * *')
+      async testJob() {
+        mockJob()
+      }
+    }
+
+    schedulerService.register(TestService)
+    schedulerService.stopAll()
+
+    // Advance time but expect no execution
+    await vi.advanceTimersByTimeAsync(3000)
+    expect(mockJob).not.toHaveBeenCalled()
+
+    // Start jobs and verify they execute
+    schedulerService.startAll()
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(mockJob).toHaveBeenCalledTimes(1)
+  })
+
+  it('should handle multiple jobs in a service', async () => {
+    const mockJob1 = vi.fn()
+    const mockJob2 = vi.fn()
+    vi.setSystemTime('2021-01-01T00:00:00.000Z')
+
+    @Schedulable()
+    class TestService {
+      @Cron('*/1 * * * * *')
+      async job1() {
+        mockJob1()
+      }
+
+      @Cron('*/2 * * * * *')
+      async job2() {
+        mockJob2()
+      }
+    }
+
+    schedulerService.register(TestService)
+
+    // After 1 second, only job1 should execute
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(mockJob1).toHaveBeenCalledTimes(1)
+    expect(mockJob2).not.toHaveBeenCalled()
+
+    // After 2 seconds, both jobs should have executed
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(mockJob1).toHaveBeenCalledTimes(2)
+    expect(mockJob2).toHaveBeenCalledTimes(1)
+  })
+
+  it('should handle disabled jobs', async () => {
+    const mockJob = vi.fn()
+
+    @Schedulable()
+    class TestService {
+      @Cron('*/1 * * * * *', { disabled: true })
+      async testJob() {
+        mockJob()
+      }
+    }
+
+    schedulerService.register(TestService)
+    const job = schedulerService.getJob(TestService, 'testJob')
+    expect(job?.isActive).toBe(false)
+
+    // Advance time but expect no execution
+    await vi.advanceTimersByTimeAsync(3000)
+    expect(mockJob).not.toHaveBeenCalled()
+  })
+
+  it('should handle errors in job execution without crashing', async () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    @Schedulable()
+    class TestService {
+      @Cron('*/1 * * * * *')
+      async testJob() {
+        throw new Error('Test error')
+      }
+    }
+
+    schedulerService.register(TestService)
+
+    // Job should not throw outside, but log the error
+    await vi.advanceTimersByTimeAsync(1000)
+
+    // Should continue executing despite previous error
+    await vi.advanceTimersByTimeAsync(1000)
+
+    // Job should still be active
+    const job = schedulerService.getJob(TestService, 'testJob')
+    expect(job?.isActive).toBe(true)
+
+    errorSpy.mockRestore()
+  })
+})

package/src/cron.constants.mts

@@ -0,0 +1,16 @@
+export enum Schedule {
+  EveryMinute = '*/1 * * * *',
+  EveryFiveMinutes = '*/5 * * * *',
+  EveryTenMinutes = '*/10 * * * *',
+  EveryFifteenMinutes = '*/15 * * * *',
+  EveryThirtyMinutes = '*/30 * * * *',
+  EveryHour = '0 * * * *',
+  EveryTwoHours = '0 */2 * * *',
+  EveryThreeHours = '0 */3 * * *',
+  EveryFourHours = '0 */4 * * *',
+  EverySixHours = '0 */6 * * *',
+  EveryTwelveHours = '0 */12 * * *',
+  EveryDay = '0 0 * * *',
+  EveryWeek = '0 0 * * 0',
+  EveryMonth = '0 0 1 * *',
+}

package/src/decorators/cron.decorator.mts

@@ -0,0 +1,30 @@
+import type { ClassType } from '@navios/core'
+import type { CronJobParams } from 'cron'
+
+import { getCronMetadata } from '../metadata/index.mjs'
+
+export interface CronOptions {
+  disabled?: boolean
+}
+
+export function Cron(
+  cronTime: CronJobParams['cronTime'],
+  options?: CronOptions,
+) {
+  return (
+    target: () => Promise<void>,
+    context: ClassMethodDecoratorContext,
+  ) => {
+    if (context.kind !== 'method') {
+      throw new Error(
+        `Cron can only be applied to methods, not ${context.kind}`,
+      )
+    }
+    if (context.metadata) {
+      const metadata = getCronMetadata(target, context)
+      metadata.cronTime = cronTime
+      metadata.disabled = options?.disabled ?? false
+    }
+    return target
+  }
+}

package/src/decorators/index.mts

@@ -0,0 +1,2 @@
+export * from './cron.decorator.mjs'
+export * from './schedulable.decorator.mjs'

package/src/decorators/schedulable.decorator.mts

@@ -0,0 +1,19 @@
+import type { ClassType } from '@navios/core'
+
+import { Injectable } from '@navios/core'
+
+import { getScheduleMetadata } from '../metadata/index.mjs'
+
+export function Schedulable() {
+  return (target: ClassType, context: ClassDecoratorContext) => {
+    if (context.kind !== 'class') {
+      throw new Error(
+        `SchedulableDecorator can only be applied to classes, not ${context.kind}`,
+      )
+    }
+    if (context.metadata) {
+      getScheduleMetadata(target, context)
+    }
+    return Injectable()(target, context)
+  }
+}

package/src/index.mts

@@ -0,0 +1,4 @@
+export * from './decorators/index.mjs'
+export * from './metadata/index.mjs'
+export * from './cron.constants.mjs'
+export * from './scheduler.service.mjs'

package/src/metadata/cron.metadata.mts

@@ -0,0 +1,52 @@
+import type { CronJobParams } from 'cron'
+
+export const CronMetadataKey = Symbol('CronMetadataKey')
+
+export interface CronMetadata {
+  classMethod: string
+  cronTime: CronJobParams['cronTime'] | null
+  disabled: boolean
+}
+
+export function getAllCronMetadata(
+  context: ClassMethodDecoratorContext | ClassDecoratorContext,
+): Set<CronMetadata> {
+  if (context.metadata) {
+    const metadata = context.metadata[CronMetadataKey] as
+      | Set<CronMetadata>
+      | undefined
+    if (metadata) {
+      return metadata
+    } else {
+      context.metadata[CronMetadataKey] = new Set<CronMetadata>()
+      return context.metadata[CronMetadataKey] as Set<CronMetadata>
+    }
+  }
+  throw new Error('[Navios-Schedule] Wrong environment.')
+}
+
+export function getCronMetadata(
+  target: Function,
+  context: ClassMethodDecoratorContext,
+): CronMetadata {
+  if (context.metadata) {
+    const metadata = getAllCronMetadata(context)
+    if (metadata) {
+      const endpointMetadata = Array.from(metadata).find(
+        (item) => item.classMethod === target.name,
+      )
+      if (endpointMetadata) {
+        return endpointMetadata
+      } else {
+        const newMetadata: CronMetadata = {
+          classMethod: target.name,
+          cronTime: null,
+          disabled: false,
+        }
+        metadata.add(newMetadata)
+        return newMetadata
+      }
+    }
+  }
+  throw new Error('[Navios-Schedule] Wrong environment.')
+}

package/src/metadata/index.mts

@@ -0,0 +1,2 @@
+export * from './cron.metadata.mjs'
+export * from './schedule.metadata.mjs'

package/src/metadata/schedule.metadata.mts

@@ -0,0 +1,55 @@
+import type { ClassType } from '@navios/core'
+
+import type { CronMetadata } from './cron.metadata.mjs'
+
+import { getAllCronMetadata } from './cron.metadata.mjs'
+
+export const ScheduleMetadataKey = Symbol('ControllerMetadataKey')
+
+export interface ScheduleMetadata {
+  name: string
+  jobs: Set<CronMetadata>
+}
+
+export function getScheduleMetadata(
+  target: ClassType,
+  context: ClassDecoratorContext,
+): ScheduleMetadata {
+  if (context.metadata) {
+    const metadata = context.metadata[ScheduleMetadataKey] as
+      | ScheduleMetadata
+      | undefined
+    if (metadata) {
+      return metadata
+    } else {
+      const jobsMetadata = getAllCronMetadata(context)
+      const newMetadata: ScheduleMetadata = {
+        name: target.name,
+        jobs: jobsMetadata,
+      }
+      context.metadata[ScheduleMetadataKey] = newMetadata
+      // @ts-expect-error We add a custom metadata key to the target
+      target[ScheduleMetadataKey] = newMetadata
+      return newMetadata
+    }
+  }
+  throw new Error('[Navios-Schedule] Wrong environment.')
+}
+
+export function extractScheduleMetadata(target: ClassType): ScheduleMetadata {
+  // @ts-expect-error We add a custom metadata key to the target
+  const metadata = target[ScheduleMetadataKey] as ScheduleMetadata | undefined
+  if (!metadata) {
+    throw new Error(
+      '[Navios-Schedule] Controller metadata not found. Make sure to use @Controller decorator.',
+    )
+  }
+  return metadata
+}
+
+export function hasScheduleMetadata(target: ClassType): boolean {
+  // @ts-expect-error We add a custom metadata key to the target
+  const metadata = target[ScheduleMetadataKey] as ScheduleMetadata | undefined
+
+  return !!metadata
+}

package/src/scheduler.service.mts

@@ -0,0 +1,93 @@
+import type { ClassType } from '@navios/core'
+
+import {
+  EnvConfigProvider,
+  inject,
+  Injectable,
+  Logger,
+  syncInject,
+} from '@navios/core'
+
+import { CronJob } from 'cron'
+
+import type { ScheduleMetadata } from './metadata/index.mjs'
+
+import {
+  extractScheduleMetadata,
+  hasScheduleMetadata,
+} from './metadata/index.mjs'
+
+@Injectable()
+export class SchedulerService {
+  // private readonly configService = syncInject(EnvConfigProvider)
+  private readonly logger = syncInject(Logger, {
+    context: SchedulerService.name,
+  })
+  private readonly jobs: Map<string, CronJob> = new Map()
+
+  register(service: ClassType) {
+    if (!hasScheduleMetadata(service)) {
+      throw new Error(
+        `[Navios-Schedule] Service ${service.name} is not schedulable. Make sure to use @Schedulable decorator.`,
+      )
+    }
+    const metadata = extractScheduleMetadata(service)
+    this.logger.debug('Scheduling service', metadata.name)
+    this.registerJobs(service, metadata)
+  }
+
+  getJob<T extends ClassType>(
+    service: T,
+    method: keyof InstanceType<T>,
+  ): CronJob | undefined {
+    const metadata = extractScheduleMetadata(service)
+    const jobName = `${metadata.name}.${method as string}()`
+    return this.jobs.get(jobName)
+  }
+
+  private registerJobs(service: ClassType, metadata: ScheduleMetadata) {
+    const jobs = metadata.jobs
+    for (const job of jobs) {
+      if (!job.cronTime) {
+        this.logger.debug('Skipping job', job.classMethod)
+        continue
+      }
+      const name = `${metadata.name}.${job.classMethod}()`
+      const self = this
+      const defaultDisabled = false
+      const cronJob = CronJob.from({
+        cronTime: job.cronTime,
+        name,
+        async onTick() {
+          try {
+            self.logger.debug('Executing job', name)
+            const instance = await inject(service)
+            await instance[job.classMethod]()
+          } catch (error) {
+            self.logger.error('Error executing job', name, error)
+          }
+        },
+        start: !(defaultDisabled || job.disabled),
+      })
+      this.jobs.set(name, cronJob)
+    }
+  }
+
+  startAll() {
+    for (const job of this.jobs.values()) {
+      if (job.isActive) {
+        continue
+      }
+      job.start()
+    }
+  }
+
+  stopAll() {
+    for (const job of this.jobs.values()) {
+      if (!job.isActive) {
+        continue
+      }
+      job.stop()
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "module": "Node16",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"],
+  "references": [
+    {
+      "path": "../core"
+    }
+  ]
+}

package/tsup.config.mts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.mts'],
+  outDir: 'lib',
+  format: ['esm', 'cjs'],
+  clean: true,
+  treeshake: 'smallest',
+  sourcemap: true,
+  platform: 'node',
+  experimentalDts: true,
+})

package/vitest.config.mts

@@ -0,0 +1,12 @@
+import { defineProject } from 'vitest/config'
+
+export default defineProject({
+  resolve: {
+    conditions: ['development', 'node', 'import'],
+  },
+  test: {
+    typecheck: {
+      enabled: true,
+    },
+  },
+})