bunsane 0.1.4 → 0.2.0

package/types/query.types.ts

@@ -0,0 +1,110 @@
+import type { BaseComponent, ComponentDataType } from "../core/components";
+import type { Entity } from "../core/Entity";
+
+/**
+ * Type constructor for a component class
+ */
+export type ComponentConstructor<T extends BaseComponent = BaseComponent> = new (...args: any[]) => T;
+
+/**
+ * Extracts the component class name from a constructor
+ */
+export type ComponentName<T extends ComponentConstructor> = T extends (new (...args: any[]) => infer C) & { name: infer N }
+    ? N
+    : string;
+
+/**
+ * Extracts component data types from a tuple of component classes.
+ * Maps [PositionCtor, VelocityCtor] -> [PositionData, VelocityData]
+ */
+export type ExtractComponentData<T extends readonly ComponentConstructor[]> = {
+    [K in keyof T]: T[K] extends ComponentConstructor<infer C>
+        ? C extends BaseComponent ? ComponentDataType<C> : never
+        : never;
+};
+
+/**
+ * Maps component constructors to a record of { ComponentName: ComponentData }.
+ * Enables access like: entity.componentData.Position.x
+ */
+export type ComponentRecord<T extends readonly ComponentConstructor[]> = {
+    [K in T[number] as K extends (new (...args: any[]) => any) & { name: infer N extends string }
+        ? N
+        : never]: K extends ComponentConstructor<infer C>
+            ? C extends BaseComponent ? ComponentDataType<C> : never
+            : never;
+};
+
+/**
+ * Union of all component constructor types in a tuple.
+ * Useful for constraining getTyped() to only accept components from the query.
+ */
+export type ComponentUnion<T extends readonly ComponentConstructor[]> = T[number];
+
+/**
+ * Entity with typed component access based on components included in query.
+ * Provides both async getTyped() and synchronous componentData access.
+ */
+export type TypedEntity<TComponents extends readonly ComponentConstructor[]> = Entity & {
+    /**
+     * Type-safe async component getter - only available for components in the query.
+     * Unlike regular get(), this returns non-null since query guarantees component exists.
+     */
+    getTyped<T extends ComponentUnion<TComponents>>(
+        ctor: T
+    ): Promise<T extends ComponentConstructor<infer C>
+        ? C extends BaseComponent ? ComponentDataType<C> : never
+        : never>;
+
+    /**
+     * Synchronous access to already-loaded component data.
+     * Available immediately after query execution without additional DB calls.
+     */
+    componentData: ComponentRecord<TComponents>;
+
+    /**
+     * The component constructors that were included in this query.
+     * Useful for runtime reflection.
+     */
+    readonly _queriedComponents: TComponents;
+};
+
+/**
+ * Result type for ArcheType queries that provides direct typed access to archetype fields.
+ * Maps archetype field names to their component data types.
+ */
+export type ArcheTypeResult<T extends object> = {
+    /** The underlying entity */
+    entity: Entity;
+    /** Entity ID shorthand */
+    id: string;
+    /** Save changes to the entity */
+    save(): Promise<void>;
+} & {
+    [K in keyof T as T[K] extends BaseComponent ? K : never]:
+        T[K] extends BaseComponent ? ComponentDataType<T[K]> : never;
+};
+
+/**
+ * Options for ArcheType queries
+ */
+export interface ArcheTypeQueryOptions {
+    /** Skip cache for this query */
+    noCache?: boolean;
+    /** Include specific relations */
+    populateRelations?: boolean;
+}
+
+/**
+ * Filter operators for typed queries
+ */
+export type TypedFilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'like' | 'ilike';
+
+/**
+ * A typed filter for archetype queries
+ */
+export interface TypedFilter<T, K extends keyof T = keyof T> {
+    field: K;
+    operator: TypedFilterOperator;
+    value: T[K] extends object ? Partial<T[K]> : T[K];
+}

package/types/scheduler.types.ts

@@ -3,7 +3,8 @@
  * Comprehensive TypeScript types for the BunSane scheduler system
  */
 
-import type { QueryFilter } from "../core/Query";
+import type { QueryFilter } from "../query/Query";
+import type { Query } from "../query/Query";
 import type { ComponentTargetConfig } from "../core/EntityHookManager";
 
 export enum ScheduleInterval {
@@ -34,14 +35,32 @@ export interface ScheduledTaskOptions {
     retryDelay?: number;
     /** Whether to continue retrying on failure */
     continueOnError?: boolean;
-    /** Query filters to apply when querying components */
-    componentFilters?: QueryFilter[];
-    /** Maximum number of entities to process per execution */
+    /** 
+     * Maximum number of entities to process per execution
+     * Note: This is applied after the query executes. For better performance,
+     * include .take() in your query function instead.
+     */
     maxEntitiesPerExecution?: number;
     /** Whether to enable task metrics collection */
     enableMetrics?: boolean;
-    /** Component targeting configuration for fine-grained entity selection */
+    /** 
+     * Component targeting configuration for fine-grained entity selection
+     * @deprecated Use query() function instead for better flexibility and readability
+     */
     componentTarget?: ComponentTargetConfig;
+    /** 
+     * Custom query function for advanced entity selection (preferred approach)
+     * @example
+     * query: () => {
+     *     return new Query()
+     *         .with(SessionComponent)
+     *         .with(PhoneComponent)
+     *         .without(AuthenticatedTag);
+     * }
+     */
+    query?: () => Query<any>;
+    /** Cron expression (when interval is CRON) */
+    cronExpression?: string;
 }
 
 export interface ScheduledTaskInfo {
@@ -49,7 +68,10 @@ export interface ScheduledTaskInfo {
     id: string;
     /** Task name */
     name: string;
-    /** Target component class (legacy - use options.componentTarget instead) */
+    /** 
+     * Target component class (legacy - use options.query instead) 
+     * @deprecated Use options.query for better flexibility
+     */
     componentTarget?: new (...args: any[]) => any;
     /** Schedule interval */
     interval: ScheduleInterval;
@@ -100,6 +122,12 @@ export interface SchedulerMetrics {
     retriedTasks: number;
     /** Task-specific metrics */
     taskMetrics: Record<string, TaskMetrics>;
+    /** Number of task executions skipped due to distributed lock unavailability */
+    skippedExecutions: number;
+    /** Total lock acquisition attempts */
+    lockAttempts: number;
+    /** Successful lock acquisitions */
+    locksAcquired: number;
 }
 
 export interface TaskMetrics {
@@ -140,7 +168,7 @@ export interface TaskExecutionResult {
 
 export interface SchedulerEvent {
     /** Event type */
-    type: 'task.registered' | 'task.executed' | 'task.failed' | 'task.timeout' | 'task.retry' | 'scheduler.started' | 'scheduler.stopped';
+    type: 'task.registered' | 'task.executed' | 'task.failed' | 'task.timeout' | 'task.retry' | 'task.skipped' | 'task.lock.acquired' | 'task.lock.released' | 'task.lock.failed' | 'scheduler.started' | 'scheduler.stopped';
     /** Task ID if applicable */
     taskId?: string;
     /** Event timestamp */
@@ -162,4 +190,37 @@ export interface SchedulerConfig {
     enableLogging: boolean;
     /** Whether to run tasks on startup */
     runOnStart: boolean;
+    /**
+     * Enable distributed locking using PostgreSQL advisory locks.
+     * When enabled, only one instance can execute a task at a time.
+     * This is essential for multi-instance deployments.
+     * @default true
+     */
+    distributedLocking?: boolean;
+    /**
+     * Lock acquisition timeout in milliseconds.
+     * If > 0, will retry acquiring the lock until timeout.
+     * If 0, immediately skips if lock is not available.
+     * @default 0
+     */
+    lockTimeout?: number;
+    /**
+     * Retry interval when attempting to acquire locks (ms).
+     * Only used when lockTimeout > 0.
+     * @default 100
+     */
+    lockRetryInterval?: number;
+}
+
+export interface DistributedLockMetrics {
+    /** Total lock acquisition attempts */
+    lockAttempts: number;
+    /** Successful lock acquisitions */
+    locksAcquired: number;
+    /** Failed lock acquisitions (another instance holds lock) */
+    locksFailed: number;
+    /** Lock acquisition timeouts */
+    lockTimeouts: number;
+    /** Tasks skipped due to lock unavailability */
+    tasksSkipped: number;
 }

package/types/upload.types.ts

@@ -88,6 +88,7 @@ export interface UploadResult {
     path?: string;
     url?: string;
     metadata?: Record<string, any>;
+    uploadedAt?: string;
     thumbnails?: Array<{ size: string; url: string; path: string }>;
     error?: UploadError;
 }

package/{core → upload}/FileValidator.ts

@@ -1,5 +1,5 @@
 import type { UploadConfiguration, ValidationResult } from "../types/upload.types";
-import { logger as MainLogger } from "./Logger";
+import { logger as MainLogger } from "../core/Logger";
 
 const logger = MainLogger.child({ scope: "FileValidator" });
 
@@ -64,6 +64,15 @@ export class FileValidator {
             errors.push(...nameValidation.errors);
         }
 
+        // Dangerous content detection
+        try {
+            if (await this.isDangerous(file)) {
+                errors.push("File contains potentially dangerous content");
+            }
+        } catch (error) {
+            warnings.push(`Could not check file safety: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+
         // Custom validation
         if (config.validation?.customValidators) {
             for (const validator of config.validation.customValidators) {

package/upload/RestUpload.ts

@@ -0,0 +1,130 @@
+import { UploadManager } from "./UploadManager";
+import type {
+    UploadConfiguration,
+    UploadResult,
+    UploadErrorCode,
+} from "../types/upload.types";
+import { logger as MainLogger } from "../core/Logger";
+
+const logger = MainLogger.child({ scope: "RestUpload" });
+
+export interface ParsedUpload {
+    file: File;
+    fieldName: string;
+}
+
+export interface RestUploadOptions {
+    config?: Partial<UploadConfiguration>;
+    storageProvider?: string;
+    maxFiles?: number;
+    fieldNames?: string[];
+}
+
+export interface RestUploadResult {
+    success: boolean;
+    files: UploadResult[];
+    fields: Record<string, string>;
+    totalFiles: number;
+    successCount: number;
+    failureCount: number;
+}
+
+export async function parseFormData(
+    req: Request,
+): Promise<{ files: ParsedUpload[]; fields: Record<string, string> }> {
+    const contentType = req.headers.get("content-type") ?? "";
+    if (!contentType.includes("multipart/form-data")) {
+        throw new Error(
+            "Invalid Content-Type: expected multipart/form-data",
+        );
+    }
+
+    const formData = await req.formData();
+    const files: ParsedUpload[] = [];
+    const fields: Record<string, string> = {};
+
+    for (const [key, value] of formData.entries()) {
+        if (typeof value !== "string") {
+            files.push({ file: value as File, fieldName: key });
+        } else {
+            fields[key] = value;
+        }
+    }
+
+    return { files, fields };
+}
+
+export async function handleUpload(
+    req: Request,
+    options: RestUploadOptions = {},
+): Promise<RestUploadResult> {
+    const { config, storageProvider, maxFiles, fieldNames } = options;
+
+    logger.info("Processing REST upload");
+
+    const { files: parsed, fields } = await parseFormData(req);
+
+    const filtered = fieldNames
+        ? parsed.filter((p) => fieldNames.includes(p.fieldName))
+        : parsed;
+
+    if (maxFiles !== undefined && filtered.length > maxFiles) {
+        throw new Error(
+            `Too many files: received ${filtered.length}, maximum is ${maxFiles}`,
+        );
+    }
+
+    const manager = UploadManager.getInstance();
+    const results: UploadResult[] = await Promise.all(
+        filtered.map((p) =>
+            manager.uploadFile(p.file, config, storageProvider),
+        ),
+    );
+
+    const successCount = results.filter((r) => r.success).length;
+    const failureCount = results.length - successCount;
+
+    logger.info(
+        `REST upload complete: ${successCount} succeeded, ${failureCount} failed`,
+    );
+
+    return {
+        success: failureCount === 0,
+        files: results,
+        fields,
+        totalFiles: results.length,
+        successCount,
+        failureCount,
+    };
+}
+
+export function uploadResponse(result: RestUploadResult): Response {
+    const status =
+        result.failureCount > 0 && result.successCount > 0
+            ? 207
+            : result.failureCount > 0
+              ? 400
+              : 200;
+
+    return new Response(JSON.stringify(result), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+
+export function uploadErrorResponse(
+    error: unknown,
+    code: UploadErrorCode = "UPLOAD_FAILED",
+    status: number = 400,
+): Response {
+    const message =
+        error instanceof Error ? error.message : "Unknown upload error";
+
+    return new Response(
+        JSON.stringify({ error: message, code }),
+        {
+            status,
+            headers: { "Content-Type": "application/json" },
+        },
+    );
+}

package/{core/components → upload}/UploadComponent.ts

@@ -1,5 +1,5 @@
-import { BaseComponent, Component, CompData } from "../Components";
-import type { UploadComponentData } from "../../types/upload.types";
+import { BaseComponent, Component, CompData } from "../core/components";
+import type { UploadResult } from "../types/upload.types";
 
 /**
  * UploadComponent - Stores file upload metadata in entities
@@ -37,15 +37,15 @@ export class UploadComponent extends BaseComponent {
     /**
      * Set upload data from UploadResult
      */
-    public setUploadData(data: UploadComponentData): void {
-        this.uploadId = data.uploadId;
-        this.fileName = data.fileName;
-        this.originalFileName = data.originalFileName;
-        this.mimeType = data.mimeType;
-        this.size = data.size;
-        this.path = data.path;
-        this.url = data.url;
-        this.uploadedAt = data.uploadedAt;
+    public setUploadData(data: UploadResult): void {
+        this.uploadId = data.uploadId ?? "";
+        this.fileName = data.fileName ?? "";
+        this.originalFileName = data.originalFileName ?? "";
+        this.mimeType = data.mimeType ?? "";
+        this.size = data.size ?? 0;
+        this.path = data.path ?? "";
+        this.url = data.url ?? "";
+        this.uploadedAt = new Date().toISOString();
         this.metadata = JSON.stringify(data.metadata || {});
     }
 

package/{core → upload}/UploadManager.ts

@@ -1,7 +1,7 @@
-import { logger as MainLogger } from "./Logger";
+import { logger as MainLogger } from "../core/Logger";
 import { uuidv7 } from "../utils/uuid";
-import type { StorageProvider } from "./storage/StorageProvider";
-import { LocalStorageProvider } from "./storage/LocalStorageProvider";
+import type { StorageProvider } from "../storage/StorageProvider";
+import { LocalStorageProvider } from "../storage/LocalStorageProvider";
 import type { UploadConfiguration, UploadResult, UploadError, FileMetadata } from "../types/upload.types";
 import { FileValidator } from "./FileValidator";
 

package/upload/index.ts

@@ -4,16 +4,21 @@
  */
 
 // Core Upload System
-export { UploadManager } from "../core/UploadManager";
-export { FileValidator } from "../core/FileValidator";
+export { UploadManager } from "./UploadManager";
+export { FileValidator } from "./FileValidator";
 
 // Storage Providers
-export { StorageProvider } from "../core/storage/StorageProvider";
-export { LocalStorageProvider } from "../core/storage/LocalStorageProvider";
+export { StorageProvider } from "../storage/StorageProvider";
+export { LocalStorageProvider } from "../storage/LocalStorageProvider";
+export { S3StorageProvider } from "../storage/S3StorageProvider";
+export type { S3StorageConfig } from "../storage/S3StorageProvider";
 
-// Components
-export { UploadComponent, ImageMetadataComponent } from "../core/components/UploadComponent";
+// REST Upload Utilities
+export { handleUpload, parseFormData, uploadResponse, uploadErrorResponse } from "./RestUpload";
+export type { ParsedUpload, RestUploadOptions, RestUploadResult } from "./RestUpload";
 
+// Components
+export { UploadComponent, ImageMetadataComponent } from "./UploadComponent";
 
 // Utilities
 export { UploadHelper } from "../utils/UploadHelper";
@@ -56,7 +61,9 @@ export type {
 } from "../types/upload.types";
 
 // Imports for internal use
-import { UploadManager } from "../core/UploadManager";
+import { UploadManager } from "./UploadManager";
+import { S3StorageProvider } from "../storage/S3StorageProvider";
+import type { S3StorageConfig } from "../storage/S3StorageProvider";
 import type { UploadConfiguration } from "../types/upload.types";
 
 /**
@@ -73,6 +80,15 @@ export async function initializeUploadSystem(config?: Partial<UploadConfiguratio
     await uploadManager.getStorageProvider("local").initialize();
 }
 
+/**
+ * Initialize S3 storage and register it with UploadManager
+ */
+export async function initializeS3Storage(config: S3StorageConfig): Promise<void> {
+    const provider = new S3StorageProvider(config);
+    await provider.initialize();
+    UploadManager.getInstance().registerStorageProvider("s3", provider);
+}
+
 /**
  * Quick setup functions for common use cases
  */

package/utils/UploadHelper.ts

@@ -1,5 +1,5 @@
-import { UploadManager } from "../core/UploadManager";
-import { UploadComponent, ImageMetadataComponent } from "../core/components/UploadComponent";
+import { UploadManager } from "../upload";
+import { UploadComponent, ImageMetadataComponent } from "../upload/UploadComponent";
 import { Entity } from "../core/Entity";
 import type { UploadConfiguration, UploadResult, BatchUploadResult } from "../types/upload.types";
 import { logger as MainLogger } from "../core/Logger";
@@ -30,6 +30,7 @@ export class UploadHelper {
                 // Create and attach upload component
                 const uploadComponent = new UploadComponent();
                 uploadComponent.setUploadData({
+                    success: result.success,
                     uploadId: result.uploadId,
                     fileName: result.fileName!,
                     originalFileName: result.originalFileName!,
@@ -42,11 +43,12 @@ export class UploadHelper {
                 });
                 
                 entity.add(UploadComponent, uploadComponent.data());
-                
+
+                // TODO: For better modularity, user might want to use plugins instead
                 // Add image metadata if it's an image
-                if (result.mimeType?.startsWith('image/')) {
-                    await this.addImageMetadata(entity, file, result);
-                }
+                // if (result.mimeType?.startsWith('image/')) {
+                //     await this.addImageMetadata(entity, file, result);
+                // }
                 
                 logger.info(`Upload component attached to entity ${entity.id}`);
             }
@@ -82,6 +84,7 @@ export class UploadHelper {
                 // Attach upload component to entity
                 const uploadComponent = new UploadComponent();
                 uploadComponent.setUploadData({
+                    success: result.success,
                     uploadId: result.uploadId!,
                     fileName: result.fileName!,
                     originalFileName: result.originalFileName!,
@@ -226,6 +229,7 @@ export class UploadHelper {
                     // Create new upload component for target entity
                     const newUpload = new UploadComponent();
                     newUpload.setUploadData({
+                        success: true,
                         uploadId: targetEntity.id,
                         fileName: sourceUpload.fileName,
                         originalFileName: sourceUpload.originalFileName,
@@ -252,6 +256,7 @@ export class UploadHelper {
                     // Remove from source and add to target
                     const newUpload = new UploadComponent();
                     newUpload.setUploadData({
+                        success: true,
                         uploadId: targetEntity.id,
                         fileName: sourceUpload.fileName,
                         originalFileName: sourceUpload.originalFileName,
@@ -302,4 +307,20 @@ export class UploadHelper {
             logger.warn(`Failed to add image metadata: ${error instanceof Error ? error.message : 'Unknown error'}`);
         }
     }
+
+    static async deleteFile(path: string): Promise<boolean> {
+        try {
+            const provider = this.uploadManager.getStorageProvider();
+            const success = await provider.delete(path);
+            if (success) {
+                logger.info(`Deleted file at path: ${path}`);
+            } else {
+                logger.warn(`File at path ${path} not found for deletion`);
+            }
+            return success;
+        } catch (error) {
+            logger.error(`Failed to delete file at path ${path}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            return false;
+        }
+    }
 }

package/utils/cronParser.ts

@@ -259,12 +259,18 @@ export class CronParser {
     static getNextExecution(cronFields: CronFields, fromDate: Date = new Date()): Date | null {
         const date = new Date(fromDate.getTime());
 
-        // Start from the next minute to avoid returning the current time if it matches
-        date.setMinutes(date.getMinutes() + 1);
-        date.setSeconds(0, 0);
+        // For 6-field expressions (with seconds), start from the next second
+        // For 5-field expressions, start from the next minute
+        const hasSeconds = !!cronFields.second;
+        if (hasSeconds) {
+            date.setSeconds(date.getSeconds() + 1);
+        } else {
+            date.setMinutes(date.getMinutes() + 1);
+            date.setSeconds(0);
+        }
 
         // Try up to 1 year in the future
-        const maxAttempts = 60 * 24 * 365; // 1 year in minutes
+        const maxAttempts = hasSeconds ? 60 * 60 * 24 * 365 : 60 * 24 * 365; // seconds or minutes
         let attempts = 0;
 
         while (attempts < maxAttempts) {
@@ -272,8 +278,12 @@ export class CronParser {
                 return new Date(date);
             }
 
-            // Move to next minute
-            date.setMinutes(date.getMinutes() + 1);
+            // Move to next second or minute
+            if (hasSeconds) {
+                date.setSeconds(date.getSeconds() + 1);
+            } else {
+                date.setMinutes(date.getMinutes() + 1);
+            }
             attempts++;
         }
 

package/.github/workflows/deploy-docs.yml

@@ -1,57 +0,0 @@
-name: Deploy Documentation to GitHub Pages
-
-on:
-  push:
-    branches: [ main ]
-    paths:
-      - 'docs/**'
-      - '.github/workflows/deploy-docs.yml'
-  pull_request:
-    branches: [ main ]
-    paths:
-      - 'docs/**'
-      - '.github/workflows/deploy-docs.yml'
-
-jobs:
-  build-and-deploy:
-    runs-on: ubuntu-latest
-
-    steps:
-    - name: Checkout
-      uses: actions/checkout@v4
-
-    - name: Setup Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version: '18'
-
-    - name: Install dependencies
-      run: |
-        cd docs
-        npm install -g docsify-cli@latest
-
-    - name: Build documentation
-      run: |
-        cd docs
-        # Generate any dynamic content if needed
-        echo "Building documentation..."
-
-    - name: Deploy to GitHub Pages
-      if: github.ref == 'refs/heads/main'
-      uses: peaceiris/actions-gh-pages@v3
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./docs
-
-  validate-links:
-    runs-on: ubuntu-latest
-    steps:
-    - name: Checkout
-      uses: actions/checkout@v4
-
-    - name: Link Checker
-      uses: lycheeverse/lychee-action@v1.8.0
-      with:
-        args: --config docs/.lychee.toml docs/
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}