@bathina_mounika/cron-generator 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# cron-generator (TypeScript)
+
+Generate cron expressions distributed across daily time slots.
+
+## Install
+
+```bash
+npm install @bathina_mounika/cron-generator
+```
+
+## Usage
+
+```typescript
+import { generate } from "@bathina_mounika/cron-generator";
+
+const crons = generate({
+  existingCrons: [],
+  runsPerDay: 4,
+  maxRunsPerSlot: 1,
+  slotSizeMinutes: 60,
+});
+// ['0 0 * * *', '0 6 * * *', '0 12 * * *', '0 18 * * *']
+```
+
+## Development
+
+```bash
+npm install
+npm test
+npm run build
+```
+
+## Publish
+
+```bash
+npm publish --access public
+```

package/dist/generator.d.ts

@@ -0,0 +1,7 @@
+export interface Config {
+    existingCrons: string[];
+    runsPerDay: number;
+    maxRunsPerSlot: number;
+    slotSizeMinutes: number;
+}
+export declare function generate(config: Config): string[];

package/dist/generator.js

@@ -0,0 +1,206 @@
+const MINUTES_PER_DAY = 1440;
+export function generate(config) {
+    const { existingCrons, runsPerDay, maxRunsPerSlot, slotSizeMinutes, } = config;
+    if (runsPerDay < 0) {
+        throw new Error("runsPerDay must be >= 0");
+    }
+    if (runsPerDay === 0) {
+        return [];
+    }
+    if (maxRunsPerSlot <= 0) {
+        throw new Error("maxRunsPerSlot must be > 0");
+    }
+    if (slotSizeMinutes <= 0) {
+        throw new Error("slotSizeMinutes must be > 0");
+    }
+    if (MINUTES_PER_DAY % slotSizeMinutes !== 0) {
+        throw new Error(`slotSizeMinutes (${slotSizeMinutes}) must evenly divide ${MINUTES_PER_DAY}`);
+    }
+    const slotsPerDay = MINUTES_PER_DAY / slotSizeMinutes;
+    const slotRuns = new Array(slotsPerDay).fill(0);
+    const slotMinutes = Array.from({ length: slotsPerDay }, () => new Set());
+    for (const expr of existingCrons) {
+        const trimmed = expr.trim();
+        if (!trimmed) {
+            continue;
+        }
+        let times;
+        try {
+            times = dailyRunMinutes(trimmed);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`invalid existing cron "${expr}": ${message}`);
+        }
+        for (const minute of times) {
+            const slot = Math.floor(minute / slotSizeMinutes);
+            slotRuns[slot] += 1;
+            slotMinutes[slot].add(minute);
+        }
+    }
+    const selectedSlots = pickSlots(slotRuns, runsPerDay, maxRunsPerSlot);
+    const crons = [];
+    for (const slot of selectedSlots) {
+        const minute = pickMinuteInSlot(slot, slotSizeMinutes, slotMinutes[slot]);
+        const hour = Math.floor(minute / 60);
+        const minOfHour = minute % 60;
+        crons.push(`${minOfHour} ${hour} * * *`);
+        slotRuns[slot] += 1;
+        slotMinutes[slot].add(minute);
+    }
+    crons.sort((a, b) => cronMinuteOfDay(a) - cronMinuteOfDay(b));
+    return crons;
+}
+function pickSlots(slotRuns, runsPerDay, maxRunsPerSlot) {
+    const slotsPerDay = slotRuns.length;
+    const occupancy = [...slotRuns];
+    const selected = [];
+    while (selected.length < runsPerDay) {
+        const preferred = runsPerDay > 0
+            ? Math.floor((selected.length * slotsPerDay) / runsPerDay)
+            : 0;
+        let bestSlot = -1;
+        let bestOcc = maxRunsPerSlot + 1;
+        let bestDistance = slotsPerDay + 1;
+        for (let offset = 0; offset < slotsPerDay; offset += 1) {
+            const slot = (preferred + offset) % slotsPerDay;
+            if (occupancy[slot] >= maxRunsPerSlot) {
+                continue;
+            }
+            if (occupancy[slot] < bestOcc) {
+                bestOcc = occupancy[slot];
+                bestSlot = slot;
+                bestDistance = offset;
+                continue;
+            }
+            if (occupancy[slot] === bestOcc && offset < bestDistance) {
+                bestSlot = slot;
+                bestDistance = offset;
+            }
+        }
+        if (bestSlot === -1) {
+            throw new Error(`cannot place ${runsPerDay} runs: only ${selected.length} slot placements available under maxRunsPerSlot`);
+        }
+        selected.push(bestSlot);
+        occupancy[bestSlot] += 1;
+    }
+    return selected;
+}
+function pickMinuteInSlot(slot, slotSize, occupied) {
+    const start = slot * slotSize;
+    const end = Math.min(start + slotSize, MINUTES_PER_DAY);
+    for (let minute = start; minute < end; minute += 1) {
+        if (!occupied.has(minute)) {
+            return minute;
+        }
+    }
+    throw new Error(`no free minute in slot ${slot}`);
+}
+function cronMinuteOfDay(expr) {
+    const fields = expr.split(/\s+/);
+    if (fields.length < 2) {
+        return 0;
+    }
+    const minute = Number.parseInt(fields[0], 10);
+    const hour = Number.parseInt(fields[1], 10);
+    return hour * 60 + minute;
+}
+function dailyRunMinutes(expr) {
+    const fields = expr.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        throw new Error(`expected 5 cron fields, got ${fields.length}`);
+    }
+    const minutes = expandField(fields[0], 0, 59);
+    const hours = expandField(fields[1], 0, 23);
+    const dayFields = fields.slice(2);
+    const names = ["day-of-month", "month", "day-of-week"];
+    for (let index = 0; index < dayFields.length; index += 1) {
+        if (dayFields[index] !== "*") {
+            throw new Error(`${names[index]} field "${dayFields[index]}" is not supported (use *)`);
+        }
+    }
+    const seen = new Set();
+    const runs = [];
+    for (const hour of hours) {
+        for (const minute of minutes) {
+            const mod = hour * 60 + minute;
+            if (seen.has(mod)) {
+                continue;
+            }
+            seen.add(mod);
+            runs.push(mod);
+        }
+    }
+    runs.sort((a, b) => a - b);
+    return runs;
+}
+function expandField(field, minVal, maxVal) {
+    if (field === "*") {
+        return range(minVal, maxVal, 1);
+    }
+    const seen = new Set();
+    const values = [];
+    for (const rawPart of field.split(",")) {
+        const part = rawPart.trim();
+        if (!part) {
+            throw new Error("empty field segment");
+        }
+        let step = 1;
+        let base = part;
+        if (part.includes("/")) {
+            const chunks = part.split("/");
+            if (chunks.length !== 2) {
+                throw new Error(`invalid step syntax "${part}"`);
+            }
+            [base] = chunks;
+            step = Number.parseInt(chunks[1], 10);
+            if (!Number.isFinite(step) || step <= 0) {
+                throw new Error(`invalid step value in "${part}"`);
+            }
+        }
+        let segment;
+        if (base === "*") {
+            segment = range(minVal, maxVal, step);
+        }
+        else if (base.includes("-")) {
+            const bounds = base.split("-");
+            if (bounds.length !== 2) {
+                throw new Error(`invalid range "${base}"`);
+            }
+            const start = Number.parseInt(bounds[0], 10);
+            const end = Number.parseInt(bounds[1], 10);
+            if (start < minVal || end > maxVal || start > end) {
+                throw new Error(`range "${base}" out of bounds [${minVal},${maxVal}]`);
+            }
+            segment = range(start, end, step);
+        }
+        else {
+            const value = Number.parseInt(base, 10);
+            if (!Number.isFinite(value)) {
+                throw new Error(`invalid value "${base}"`);
+            }
+            if (value < minVal || value > maxVal) {
+                throw new Error(`value ${value} out of bounds [${minVal},${maxVal}]`);
+            }
+            segment = [value];
+        }
+        for (const value of segment) {
+            if (!seen.has(value)) {
+                seen.add(value);
+                values.push(value);
+            }
+        }
+    }
+    if (values.length === 0) {
+        throw new Error(`field "${field}" expanded to no values`);
+    }
+    values.sort((a, b) => a - b);
+    return values;
+}
+function range(start, end, step) {
+    const values = [];
+    for (let value = start; value <= end; value += step) {
+        values.push(value);
+    }
+    return values;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { generate } from "./generator.js";
+export type { Config } from "./generator.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { generate } from "./generator.js";

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@bathina_mounika/cron-generator",
+  "version": "0.1.0",
+  "description": "Generate cron expressions distributed across daily time slots",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bathinaMounika/cron-generator.git",
+    "directory": "typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/bathinaMounika/cron-generator/issues"
+  },
+  "homepage": "https://github.com/bathinaMounika/cron-generator#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "cron",
+    "scheduler",
+    "generator"
+  ],
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.7"
+  }
+}