webspresso 0.0.98 → 0.0.100

package/.agents/ORM.md

@@ -122,17 +122,32 @@ const result = await productRepo.query()
 
 ---
 
-## 3. Relations & Eager Loading
+## 3. Relations & Nested Eager Loading
 
-Support for `belongsTo`, `hasMany`, and `hasOne`:
+Support for `belongsTo`, `hasMany`, and `hasOne` with arbitrary-depth batch nested loading:
 
 ```js
-// Eager-load relations using include
-const productsWithCategory = await productRepo.query()
+// 1. Direct eager loading
+const products = await productRepo.query()
   .include('category', 'reviews')
   .find();
+
+// 2. Nested eager loading (dot notation)
+const posts = await postRepo.query()
+  .include('author.profile', 'author.company.country', 'comments.author')
+  .find();
+
+// 3. Eager loading via repository methods
+const post = await postRepo.findById(id, { include: ['author.profile'] });
+const list = await postRepo.find({ active: true }, { include: ['author.company'] });
+
+// 4. Shorthand repository chaining
+const result = await postRepo.include('author.profile').where('user_id', 1).find();
 ```
 
+> [!TIP]
+> Nested relations are loaded using optimized batch queries (`whereIn`) with zero N+1 queries. Shared object references and JSON columns on related models are automatically handled.
+
 ---
 
 ## 4. Ambient Transactions & AsyncLocalStorage
@@ -228,3 +243,162 @@ defineModel({
 - **Include Guards**: Excessive `query().with(...)` or `?include=...` relations beyond `maxIncludes` throw `QueryComplexityError` or safely cap relations.
 - **REST Resources Protection**: Automatically validates client parameters (`?perPage=5000` or `?include=...`) against model complexity boundaries.
 
+---
+
+## 8. Universal Full-Text Search (FTS)
+
+Webspresso ORM provides database-agnostic full-text and keyword search with transparent dialect optimizations for SQLite, PostgreSQL, and MySQL.
+
+### 8.1 Model Configuration (`searchable`)
+
+Declare default searchable columns on your model:
+
+```javascript
+defineModel({
+  name: 'Article',
+  table: 'articles',
+  schema: zdb.schema({
+    id: zdb.id(),
+    title: zdb.string(),
+    content: zdb.text(),
+    author: zdb.string(),
+  }),
+  searchable: ['title', 'content'], // Default columns for .search()
+});
+```
+
+*(Note: If `searchable` is not defined, `.search()` automatically falls back to `admin.searchFields` if available.)*
+
+### 8.2 Using Search in Application Code
+
+Search is available both on repository instances (`repo.search`) and on query builders (`query().search()` / `query().orSearch()`):
+
+```javascript
+const articleRepo = req.db.getRepository('Article');
+
+// 1. Basic search across default searchable columns
+const results = await articleRepo.search('webspresso framework').get();
+
+// 2. Chained with filtering, ordering, and pagination
+const page = await articleRepo
+  .search(req.query.q) // Safe no-op when req.query.q is empty or undefined
+  .where('status', 'published')
+  .orderBy('created_at', 'desc')
+  .paginate({ page: 1, limit: 10 });
+
+// 3. Dynamic column override
+const byAuthor = await articleRepo.search('Alice', ['author']).get();
+
+// 4. Exact phrase matching
+const exact = await articleRepo.search('zero dependency sprawl', null, { exact: true }).get();
+
+// 5. OR matching between words (default is AND)
+const anyWord = await articleRepo.search('vue react angular', null, { matchAllWords: false }).get();
+
+// 6. Disjoined search conditions with orSearch()
+const mixed = await articleRepo.query()
+  .where('author', 'Bob')
+  .orSearch('featured article', ['title'])
+  .get();
+```
+
+### 8.3 Dialect Features & Modes
+
+| Dialect | Mode (`options.mode`) | SQL Strategy | Notes |
+| :--- | :--- | :--- | :--- |
+| **SQLite** | `'auto'` (default) | Tokenized case-insensitive `LIKE` | Safe out-of-the-box, no virtual table required. |
+| **SQLite** | `'fts'` | `articles MATCH ?` or virtual table subquery | Set `{ mode: 'fts', ftsTable: 'articles_fts' }` for FTS5 tables. |
+| **PostgreSQL** | `'auto'` / `'fts'` | `to_tsvector @@ plainto_tsquery` / `websearch_to_tsquery` | Native Postgres tsvector search. Pass `{ rank: true }` to order by `ts_rank` relevance. |
+| **MySQL** | `'fts'` | `MATCH(...) AGAINST(? IN BOOLEAN MODE)` | Requires FULLTEXT index on table. |
+
+---
+
+## 9. Relational Cascading Soft-Delete & Selective Restore (`cascade: true`)
+
+Webspresso ORM supports automated relational cascade operations for `hasMany` and `hasOne` relationships. When a parent record is soft-deleted or restored, child records are synchronized automatically.
+
+### 9.1 Relation Configuration
+
+Configure `cascade` directly inside your model relations:
+
+```javascript
+defineModel({
+  name: 'Author',
+  table: 'authors',
+  schema: zdb.schema({
+    id: zdb.id(),
+    name: zdb.string(),
+    deleted_at: zdb.timestamp({ nullable: true }),
+  }),
+  relations: {
+    // 1. Full cascade (soft-delete, hard-delete, and restore)
+    posts: {
+      type: 'hasMany',
+      model: () => 'Post', // or () => Post
+      foreignKey: 'author_id',
+      cascade: true,
+    },
+    // 2. hasOne cascade
+    profile: {
+      type: 'hasOne',
+      model: () => 'Profile',
+      foreignKey: 'author_id',
+      cascade: true,
+    },
+    // 3. Delete-only cascade (child is deleted with parent, but NOT restored)
+    tokens: {
+      type: 'hasMany',
+      model: () => 'ApiToken',
+      foreignKey: 'author_id',
+      cascade: 'delete', // or { delete: true, restore: false }
+    },
+  },
+  scopes: {
+    softDelete: true,
+  },
+});
+```
+
+### 9.2 Cascade Deletion Behavior
+
+- **Soft Delete (`repo.delete(id)`)**:
+  When an Author is soft-deleted, all active child records in cascading relations (`hasMany`, `hasOne`) are soft-deleted with the **exact same `deleted_at` timestamp**.
+  Cascade is recursive: If `Post` also defines `comments` with `cascade: true`, all comments under those posts are cascaded automatically.
+- **Hard Delete (`repo.forceDelete(id)`)**:
+  When `forceDelete` is called (or when parent is a non-softDelete model), cascading child records are deleted **before** the parent to avoid foreign-key constraint violations (`FOREIGN KEY constraint failed`).
+- **Cache Invalidation**:
+  The ORM query cache for all affected related models is automatically invalidated.
+
+### 9.3 Selective Restore (Smart Timestamp Matching)
+
+A classic pitfall in soft-delete architectures is resurrecting child records that the user deliberately deleted prior to deleting the parent account:
+
+```
+T1 (10:00): User manually deletes Post #1 (deleted_at = 10:00).
+T2 (12:00): User account is soft-deleted (deleted_at = 12:00).
+            Post #2 and Post #3 receive deleted_at = 12:00.
+T3 (15:00): User account is restored.
+```
+
+By default, Webspresso ORM executes **selective restore**:
+- It restores only child records where `child.deleted_at === parent.deleted_at` (Post #2 and Post #3).
+- Post #1 remains soft-deleted because its `deleted_at` was `10:00`!
+
+```javascript
+// Default: Safe selective restore (protects previously deleted children)
+await authorRepo.restore(authorId);
+
+// Optional: Force restore ALL children regardless of when they were deleted
+await authorRepo.restore(authorId, { allChildren: true });
+
+// Optional: Bypass cascading for a specific operation
+await authorRepo.delete(authorId, { cascade: false });
+await authorRepo.restore(authorId, { cascade: false });
+```
+
+### 9.4 Cycle & Recursion Safety
+
+If your data model contains circular relations (e.g. `User.partner` <-> `Partner.user`), Webspresso ORM uses an internal visited set (`model:id`) to terminate recursion cleanly without stack overflows.
+
+
+

package/.agents/PLUGINS.md

@@ -77,7 +77,79 @@ Zero-dependency HTTP Basic Authentication (RFC 7617) plugin with timing-safe equ
   - `onAuthenticated`: Callback hook `(req, user) => ...`.
 - **Named Middleware**: Registers `ctx.middlewares.basicAuth` for route files.
 
-### 2.2 `adminPanelPlugin` (`plugins/admin-panel`)
+### 2.2 `apiKeyPlugin` (`plugins/api-key`)
+Zero-dependency B2B & Developer API Key Management Plugin with standard prefix format (`wsp_live_...`), SHA-256 secure hash storage, timing-safe constant-time verification (`crypto.timingSafeEqual`), granular scopes/permissions with wildcard support, non-blocking `last_used_at` usage tracking, and programmatic creation/revocation APIs.
+- **Options**:
+  - `db` / `knex`: Webspresso Database or Knex instance.
+  - `tableName`: Database table name (default `'api_keys'`).
+  - `prefix`: Default key prefix (default `'wsp_live_'`).
+  - `byteLength`: Random byte count for key generation (default `24`).
+  - `global`: Boolean, whether to protect routes globally (default `false`).
+  - `routes`: Route prefix(es) to protect when `global: true`.
+  - `skipPaths` / `skip`: Exclusion paths or predicate function `(req) => boolean`.
+  - `keys`: Static in-memory keys for testing / serverless / simple setups (`[{ key, name, scopes }]` or map).
+  - `trackUsage`: Boolean (default `true`), whether to automatically update `last_used_at` on verified keys.
+  - `updateLastUsedThrottleMs`: Throttle period in ms to avoid DB write thrashing (default `60000`).
+  - `allowQueryParam`: Boolean (default `false`), allow extracting API key via `?apiKey=...`.
+  - `findKeyByHash` / `verify`: Custom key lookup or verification hook.
+  - `getUser`: Custom async user resolver `(apiKeyRecord, req) => Promise<User | null>`.
+  - `onAuthenticated`: Callback hook `(req, apiKeyRecord) => void`.
+- **Named Middleware**:
+  - `middleware: ['apiKey']`: Requires valid API key via `X-API-Key`, `api-key`, or `Authorization: Bearer <key>`.
+  - `middleware: [['apiKey', { scopes: ['reports:read', 'orders:*'] }]]`: Enforces required granular scopes with prefix wildcard support (`*`, `namespace:*`).
+  - `middleware: [['apiKey', { optional: true }]]`: Non-blocking authentication (populates `req.apiKey` if present, passes through if absent).
+- **Request Context Injected**:
+  - `req.apiKey`: The authenticated API key record (including name, key_hint, scopes, metadata).
+  - `req.auth.apiKey`: Equivalent reference inside `req.auth`.
+  - `req.auth.user` & `req.user`: Associated user record (if `user_id` or `getUser` resolved).
+- **Programmatic API (`apiKeyPlugin.api`)**:
+  - `generateKey(options)`: Generate fresh key with hash and masked hint (`wsp_live_...4f2a`).
+  - `hashKey(rawKey)`: Compute SHA-256 hex string.
+  - `maskKey(rawKey, prefix)`: Mask raw key for logs/UI.
+  - `createApiKey(data, options)`: Generates key, hashes it, and stores in database table (returns raw key once).
+  - `verifyApiKey(rawKey, options)`: Verify raw key against DB, checking expiration and revocation.
+  - `revokeApiKey(idOrHash, options)`: Mark key as revoked in DB (`revoked_at = now()`).
+  - `getMigrationTemplate(tableName)`: Knex migration script creating `api_keys` table.
+  - `createApiKeyModel(tableName)`: Webspresso ORM model definition with hidden `key_hash`.
+
+### 2.3 `webhooksPlugin` (`plugins/webhooks`)
+Outgoing Webhook Dispatcher and Management Plugin with zero external dependencies. Dispatches events to subscribed external HTTP endpoints, signs payloads with HMAC-SHA256 (`X-Webspresso-Signature` and standard timestamped `webhook-signature`), filters events with wildcards (`*`, `order.*`), automatically retries failed deliveries using exponential backoff, hooks directly into Webspresso Queue (`core/queue`), and provides an interactive Mithril.js Admin Panel management UI.
+- **Options**:
+  - `db` / `knex`: Webspresso Database or Knex instance.
+  - `endpointsTable`: Database table for endpoints (default `'webhook_endpoints'`).
+  - `deliveriesTable`: Database table for delivery logs (default `'webhook_deliveries'`).
+  - `maxAttempts`: Maximum retry attempts on delivery failure (default `3`).
+  - `backoffBaseMs`: Base delay for exponential backoff in milliseconds (default `1000`).
+  - `timeoutMs`: HTTP request timeout in milliseconds (default `10000`).
+  - `wrapPayload`: Boolean (default `true`), wrap data in standard `{ id, event, timestamp, data }` event envelope.
+  - `queue`: Custom `QueueManager` instance (auto-detected from `ctx.app.queue` if present).
+  - `endpoints`: Static in-memory endpoints array (useful for testing or serverless setups).
+  - `apiPrefix`: Admin REST API prefix (default `'/webhooks'`).
+  - `includeDefaultPage`: Register Admin UI page and sidebar menu item (default `true`).
+  - `pageTitle`: Admin page title (default `'Webhooks'`).
+  - `menuOrder`: Admin sidebar order (default `92`).
+- **Request & Application Context Injected**:
+  - `req.webhooks`: Direct reference to the `WebhookDispatcher` instance.
+  - `app.webhooks`: Direct reference on the Webspresso Application instance.
+- **Built-in Services Registered**:
+  - `'webhook.dispatch'`: Dispatch events via `ctx.service('webhook.dispatch', { event, payload })`.
+  - `'webhook.ping'`: Test endpoint connectivity via `ctx.service('webhook.ping', { endpointId })`.
+  - `'webhook.retry'`: Manually retry a delivery via `ctx.service('webhook.retry', { deliveryId })`.
+- **Programmatic API (`webhooksPlugin.api` / `dispatcher`)**:
+  - `dispatch(event, payload, options)`: Match endpoints and deliver payload asynchronously (or await with `wait: true`).
+  - `pingEndpoint(endpointId)`: Send a test `ping` event to verify destination connectivity.
+  - `retryDelivery(deliveryId)`: Re-send a failed delivery with incremented attempt count.
+  - `createEndpoint(data)`: Register a new webhook endpoint with custom or auto-generated `whsec_` secret.
+  - `updateEndpoint(id, data)` / `deleteEndpoint(id)`: Update or delete endpoint records.
+  - `listEndpoints(filters)`: List endpoints with delivery statistics.
+  - `listDeliveries(filters)`: Query delivery logs with filtering by endpoint, event, and success status.
+  - `purgeDeliveries(options)`: Purge logs older than specified retention days.
+  - `signPayload(payload, secret, options)`: Compute HMAC-SHA256 signature (`sha256=...` and `t=...,v1=...`).
+  - `verifySignature(payload, header, secret, options)`: Constant-time signature verification with drift tolerance.
+  - `getMigrationTemplate()`: Knex migration script for `webhook_endpoints` and `webhook_deliveries`.
+  - `getModels()`: Webspresso ORM model definitions for `WebhookEndpoint` and `WebhookDelivery`.
+
+### 2.4 `adminPanelPlugin` (`plugins/admin-panel`)
 Mithril.js SPA Admin Panel mounted at `/_admin`.
 - **Options**: `{ path: '/_admin', db, title: 'Webspresso Admin' }`
 - **Features**: Auto CRUD screens for ORM models, user staff auth, custom page registration, widgets, field renderers.
@@ -96,14 +168,14 @@ Multipart file upload manager with local / cloud storage providers.
 
 ### 2.5 `fileManagerPlugin` (`plugins/file-manager`)
 Filesystem-first media library, directory explorer, and modal asset picker for Admin Panel.
-- **Options**: `{ baseDir: './public/uploads', publicBasePath: '/uploads', apiPrefix: '/files', pageTitle: 'Dosya Yöneticisi', maxUploadBytes: 10485760, allowedExtensions, allowedMimeTypes, includePage: true }`
+- **Options**: `{ baseDir: './public/uploads', publicBasePath: '/uploads', apiPrefix: '/files', pageTitle: 'File Manager', maxUploadBytes: 10485760, allowedExtensions, allowedMimeTypes, includePage: true }`
 - **Features**:
   - Directory tree navigation (breadcrumbs), safe subfolder creation (`mkdir`), item rename, delete, and move.
   - Path traversal attack protection (`resolveSafePath`).
   - Grid (thumbnail gallery) & List (table) view modes.
   - Search by filename and type filter (Images, Documents, Videos, Audio, Archives, Code).
   - Media preview modal with copy URL and direct playback/preview.
-  - "Kütüphaneden Seç" modal picker integrated with `FileUploadField` and `zdb.file()` form fields.
+  - "Choose from Media Library" modal picker integrated with `FileUploadField` and `zdb.file()` form fields.
   - Built-in services: `fileManager.list`, `fileManager.mkdir`, `fileManager.rename`, `fileManager.delete`, `fileManager.move`, `fileManager.upload`.
 
 ### 2.6 `corsPlugin` (`plugins/cors`)
@@ -217,23 +289,37 @@ Polar.sh subscription billing — checkout, customer portal, webhooks, Customer
   - [docs/guides/polar-production-checklist.md](../docs/guides/polar-production-checklist.md)
 
 ### 2.12 `auditLogPlugin` (`plugins/audit-log`)
-Admin mutation tracking and audit history with scheduled retention and manual purge API.
+Admin mutation tracking, record change timeline, and audit history with scheduled retention and manual purge API.
 - **Options**:
   - `db`: Database instance (must expose `.knex`).
   - `tableName`: Database table name (default `'audit_logs'`).
+  - `registerRecordAction`: Register built-in "Timeline" action on all admin models (default `true`).
   - `retentionDays`: Days to retain audit trail entries (default `90`).
   - `cleanupIntervalMs`: Background cleanup timer frequency (default 24h).
   - `autoCleanup`: Enable scheduled background purge (default `true`).
   - `cleanupOnStart`: Run initial purge shortly after boot (default `true`).
   - `retention`: `{ enabled, days: 90, intervalMs: 86400000, runOnStart: true }` (or `false` to disable).
+- **Timeline UI Features**:
+  - **Dual Mode**: Switch seamlessly between **Timeline View** and **Table View**.
+  - **Record Focus Mode**: Clicking any `Model #ID` tag instantly filters and displays that specific record's revision timeline.
+  - **Visual Spine & Status Icons**: Color-coded action nodes for `create` (emerald +), `update` (blue ✏️), `delete` (rose 🗑️), and `restore` (amber ↺).
+  - **Changed Fields Diff**: Clearly lists modified fields (e.g. `title`, `price`) on every update event.
+  - **Expandable Details**: Inspect full HTTP request path, actor IP, user agent, and pretty-printed JSON metadata.
+  - **Built-in Record Action**: One-click "Timeline" button on record lists and edit forms jumps straight to that record's audit history.
+- **API & Admin Panel Endpoints**:
+  - `GET /_admin/api/audit-logs`: List paginated logs with filters (`model`, `recordId`, `action`, `search`, `from`, `to`).
+  - `GET /_admin/api/audit-logs/timeline/:model/:id`: Dedicated chronological record change timeline with summary stats.
+  - `POST /_admin/api/audit-logs/purge`: `{ days: 90 }` or `{ olderThan: '2026-01-01' }`.
+- **Programmatic Plugin API**:
+  ```javascript
+  const audit = ctx.usePlugin('audit-log');
+  const history = await audit.queryTimeline('Post', 42);
+  const logs = await audit.queryLogs({ model: 'User', action: 'delete' });
+  ```
 - **Pruning CLI**:
   ```bash
   webspresso audit:prune --days 90
   ```
-- **API & Admin Panel**:
-  - `POST /_admin/api/audit-logs/purge`: `{ days: 90 }` or `{ olderThan: '2026-01-01' }`
-  - "Purge 90d" button directly in the Admin Panel audit log viewer.
-  - Lifecycle integration: background timers use `.unref()` and clean up on server shutdown.
 
 ### 2.13 `ormCacheAdminPlugin` (`plugins/orm-cache-admin`)
 ORM Cache inspection and invalidation dashboard.
@@ -558,6 +644,25 @@ Interactive Webspresso Developer Dashboard SPA mounted at `/_webspresso` and Flo
     - **💻 System Tab**: Process uptime, memory usage, environment, and Node platform metrics.
   - **Zero Production Overhead**: When `process.env.NODE_ENV === 'production'`, `devToolbar()` immediately returns `""` with zero overhead.
 
+### 2.19 `oauthPlugin` (`plugins/oauth`)
+Zero-dependency OAuth 2.0 & Social Login plugin supporting Google, GitHub, and custom providers with RFC 7636 PKCE, HMAC-signed anti-CSRF state tokens, and Dual Auth integration.
+- **Options**:
+  - `secret`: Secret key for HMAC state signing (`process.env.OAUTH_SECRET || process.env.SESSION_SECRET`).
+  - `pathPrefix`: Base path for OAuth routes (default `'/auth'`).
+  - `providers`: Provider configuration dictionary (`google`, `github`, or custom).
+  - `defaultReturnTo`: Fallback redirect path after successful login (default `'/'`).
+  - `failureRedirect`: Redirect path on OAuth failure (default `'/login'`).
+  - `findOrCreateUser`: `async ({ provider, profile, tokens, db, req, res }) => user`.
+  - `onSuccess`: `async ({ provider, user, profile, tokens, stateData, req, res, client }) => void`.
+  - `onError`: `async ({ error, provider, req, res, client }) => void`.
+- **Automatic Routes**:
+  - `GET /auth/:provider`: Initiates OAuth authorization flow with PKCE and signed state.
+  - `GET /auth/:provider/callback`: Exchanges authorization code, fetches normalized profile, links or creates user, and logs into session or returns JWT token.
+- **Template Helper**:
+  - `fsy.oauthUrl('google')` ➔ `"/auth/google"`
+  - `fsy.oauthUrl('github', { returnTo: '/dashboard' })` ➔ `"/auth/github?returnTo=%2Fdashboard"`
+
+
 
 
 

package/.agents/QUEUE.md

@@ -154,3 +154,95 @@ webspresso queue:prune --days 7
 webspresso queue:prune --days 14 --status completed,failed
 ```
 
+---
+
+## 6. Cron & Recurring Task Scheduler
+
+Webspresso includes a native, zero-dependency task scheduler with a POSIX-compliant 5-field cron parser (`core/queue/cron.js` & `core/queue/scheduler.js`).
+
+### 1. Cron Expression Syntax
+- Standard 5 fields: `minute hour day-of-month month day-of-week`
+- Wildcards: `*`, `?` (supported in day-of-month and day-of-week)
+- Steps & Offsets: `*/5`, `10/15` (starting at minute 10, every 15 min), `10-30/5`
+- Ranges: `1-5`, `5-7` (Fri-Sun), `MON-FRI`, `MON-SUN`, `JAN-DEC`
+- Lists: `1,15,30`, `MON,WED,FRI`
+- Descriptive aliases:
+  - `@yearly`, `@annually` (`0 0 1 1 *`)
+  - `@monthly` (`0 0 1 * *`)
+  - `@weekly` (`0 0 * * 0`)
+  - `@weekdays`, `@workdays` (`0 0 * * 1-5`)
+  - `@weekends` (`0 0 * * 6,0`)
+  - `@daily`, `@midnight` (`0 0 * * *`)
+  - `@hourly`, `@every_hour` (`0 * * * *`)
+  - `@every_minute`, `@minutely` (`* * * * *`)
+  - `@every <N>m` (e.g. `@every 5m` → `*/5 * * * *`)
+  - `@every <N>h` (e.g. `@every 2h` → `0 */2 * * *`)
+  - `@every <N>d` (e.g. `@every 2d` → `0 0 */2 * *`)
+
+### 2. Programmatic Scheduling
+```js
+// Schedule daily digest at 09:00 AM with Timezone support
+queue.schedule('0 9 * * *', 'reports.daily-digest', { channel: 'slack' }, {
+  timezone: 'Europe/Istanbul', // IANA timezone support ('Europe/Istanbul', 'America/New_York')
+  overlap: false,              // Prevent concurrent execution if previous run is still active (default: false)
+  maxRuns: 10,                 // Optional maximum executions before auto-unscheduling
+});
+
+// Or use the .cron() alias
+queue.cron('@every 15m', 'metrics.collect');
+
+// Query schedules
+const schedules = queue.getSchedules();
+// [{ id, name, cronExpression, nextRunAt, lastRunAt, isRunning, activeJobId, activeJobIds, runsCount, ... }]
+
+// Manually trigger a schedule immediately
+await queue.triggerSchedule('reports.daily-digest');
+
+// Unschedule by schedule ID or job name (removes all schedules matching the job name)
+queue.unschedule('metrics.collect');
+```
+
+### 3. Schedule Options
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `id` | `string` | `schedule:${job}:${cron}` | Custom unique identifier |
+| `overlap` | `boolean` | `false` | When `false`, skips tick if a previous job run is still processing |
+| `preventOverlap` | `boolean` | `true` | Alias for `overlap: false` |
+| `maxRuns` | `number` | `null` | Automatically unschedules task after N runs |
+| `utc` | `boolean` | `false` | Evaluate cron expressions in UTC instead of local timezone |
+| `timezone` (`tz`) | `string` | `null` | IANA timezone name (e.g. `'Europe/Istanbul'`, `'America/New_York'`) |
+| `runImmediately` | `boolean` | `false` | Triggers a run right after scheduling |
+
+### 4. File-Based Cron Discovery (`jobs/`)
+Jobs in the `jobs/` folder can automatically declare their recurrence in two ways:
+
+#### Option A: `cron` / `schedule` property in job module
+```js
+// jobs/reports/summary.js
+module.exports = async function(job, ctx) {
+  // run summary logic...
+};
+
+module.exports.cron = '0 8 * * 1-5'; // Every weekday at 8:00 AM
+module.exports.data = { reportType: 'executive' };
+module.exports.options = {
+  overlap: false,
+};
+```
+
+#### Option B: `.cron.js` file naming
+```js
+// jobs/cleanup-logs.cron.js (auto-discovers job name 'cleanup-logs')
+module.exports = {
+  cron: '@daily',
+  handler: async function(job, ctx) {
+    // perform cleanup
+  },
+};
+```
+
+### 5. Lifecycle & Overlap Management
+- The scheduler automatically pauses when `queue.pause()` is called and resumes with `queue.resume()`.
+- On `queue.drain()` or `queue.stop()`, recurring schedules are stopped and active dispatched jobs are given time to complete.
+- Overlap prevention (`overlap: false`) hooks into `job:completed` and `job:failed` events, ensuring slow asynchronous tasks never collide or duplicate.
+