refactor: standardize import statements and enhance README with immediate/delayed first run and overrun protection examples

Author: chaqchase

README.md

@@ -46,6 +46,11 @@ Cronbake provides two scheduling modes for optimal performance:
 - **Calculated Timeouts** (default): More efficient scheduling using precise timeout calculations
 - **Polling Interval**: Traditional polling-based scheduling with configurable intervals
 
+Additional scheduling controls:
+
+- **Immediate/Delayed First Run**: Run the first callback immediately (`immediate: true`) or after a delay (`delay: '10s'`).
+- **Overrun Protection**: Skip new starts if a previous run is still executing (`overrunProtection: true`).
+
 #### Cron Job Management
 
 Cronbake provides a simple and intuitive interface for managing cron jobs. You can easily add, remove, start, stop, pause, resume, and destroy cron jobs using the `Baker` class.
@@ -77,7 +82,7 @@ Track detailed execution history and performance metrics including:
 
 Cronbake supports job persistence across application restarts:
 
-- Save job state to file system
+- Save job state to file system or Redis (pluggable providers)
 - Automatic restoration on startup
 - Configurable persistence options
 
@@ -156,6 +161,27 @@ const everyMinuteJob = baker.add({
 baker.bakeAll();
 ```
 
+#### Immediate/Delayed First Run and Overrun Protection
+
+```typescript
+import Baker from 'cronbake';
+
+const baker = Baker.create();
+
+baker.add({
+  name: 'fast-job',
+  cron: '@every_10_seconds',
+  immediate: true,      // run the first time right away
+  delay: '2s',          // but wait 2 seconds before that first run
+  overrunProtection: true, // skip overlaps if a previous run still executes
+  callback: async () => {
+    // Do work
+  },
+});
+
+baker.bakeAll();
+```
+
 #### Advanced Configuration
 
 You can configure the Baker with advanced options:
@@ -254,6 +280,35 @@ await baker.saveState();
 await baker.restoreState();
 ```
 
+#### Persistence Providers (File and Redis)
+
+Cronbake uses pluggable providers for persistence. A file provider is included by default. A Redis provider is available; you inject your Redis client.
+
+```typescript
+import { Baker, FilePersistenceProvider, RedisPersistenceProvider } from 'cronbake';
+
+// File-based
+const bakerFile = Baker.create({
+  persistence: {
+    enabled: true,
+    strategy: 'file',
+    provider: new FilePersistenceProvider('./cronbake-state.json'),
+    autoRestore: true,
+  },
+});
+
+// Redis-based (provide your own client implementing get/set)
+const redisProvider = new RedisPersistenceProvider({ client: redisClient, key: 'cronbake:state' });
+const bakerRedis = Baker.create({
+  persistence: {
+    enabled: true,
+    strategy: 'redis',
+    provider: redisProvider,
+    autoRestore: true,
+  },
+});
+```
+
 ### Baker Methods
 
 | Method | Description |
@@ -309,6 +364,8 @@ const job = Cron.create({
     console.error('Job failed:', error.message);
   },
   priority: 10,
+  immediate: false,
+  overrunProtection: true,
 });
 
 // Start the cron job
@@ -326,8 +383,11 @@ const nextExecution = job.nextExecution();
 // Get metrics and history
 const metrics = job.getMetrics();
 const history = job.getHistory();
+// Metrics include skippedExecutions when overrun protection skips overlaps
 ```
 
+ 
+
 Cronbake also provides utility functions for parsing cron expressions, getting the next or previous execution times, and validating cron expressions.
 
 ```typescript
@@ -370,4 +430,4 @@ Contributions are welcome! If you find any issues or have suggestions for improv
 
 ## License
 
-Cronbake is released under the [MIT License](./LICENSE).
+Cronbake is released under the [MIT License](./LICENSE).

index.ts

@@ -1,4 +1,4 @@
-import Baker from './lib';
+import Baker from "./lib";
 
 export {
   type CronOptions,
@@ -17,7 +17,17 @@ export {
   type OnDayStrType,
   type day,
   type unit,
-} from './lib';
+} from "./lib";
 
-export { Cron, Baker, CronParser } from './lib';
+export { Cron, Baker, CronParser } from "./lib";
 export default Baker;
+
+export {
+  FilePersistenceProvider,
+  RedisPersistenceProvider,
+  PersistedJob,
+  PersistedState,
+  PersistenceProvider,
+  RedisLikeClient,
+  RedisProviderOptions,
+} from "./lib/persistence";

lib/persistence.test.ts

@@ -18,8 +18,10 @@ describe('Persistence Providers', () => {
     });
     await sleep(10);
     expect(baker2.getJobNames()).toContain('file-job');
-    baker2.destroyAll();
-    baker1.destroyAll();
+    // Stop timers and persist final state before cleanup
+    baker2.stopAll();
+    baker1.stopAll();
+    await baker2.saveState();
     cleanupFile(filePath);
   });
 

lib/persistence/file.ts

@@ -3,26 +3,44 @@ import * as path from "path";
 import { PersistedState, PersistenceProvider } from "./types";
 
 class FilePersistenceProvider implements PersistenceProvider {
+  private queue: Promise<void> = Promise.resolve();
+
   constructor(private filePath: string) {}
 
   async save(state: PersistedState): Promise<void> {
     const filePath = path.resolve(this.filePath);
     const dir = path.dirname(filePath);
+    const tmp = `${filePath}.tmp`;
+
     if (!fs.existsSync(dir)) {
       fs.mkdirSync(dir, { recursive: true });
     }
-    await fs.promises.writeFile(filePath, JSON.stringify(state, null, 2), "utf8");
+
+    const write = async () => {
+      const data = JSON.stringify(state, null, 2);
+      // Atomic write: write to temp, then rename over destination
+      await fs.promises.writeFile(tmp, data, "utf8");
+      await fs.promises.rename(tmp, filePath);
+    };
+
+    // Serialize writes to avoid interleaving
+    this.queue = this.queue.then(write, write);
+    return this.queue;
   }
 
   async load(): Promise<PersistedState | null> {
     const filePath = path.resolve(this.filePath);
     if (!fs.existsSync(filePath)) return null;
-    const data = await fs.promises.readFile(filePath, "utf8");
-    const state = JSON.parse(data);
-    if (!state || typeof state !== "object") return null;
-    return state as PersistedState;
+    try {
+      const data = await fs.promises.readFile(filePath, "utf8");
+      const state = JSON.parse(data);
+      if (!state || typeof state !== "object") return null;
+      return state as PersistedState;
+    } catch {
+      // If file is mid-write or corrupted, return null so caller can retry later
+      return null;
+    }
   }
 }
 
 export { FilePersistenceProvider };
-