bunsane 0.3.2 → 0.5.0

package/core/hooks/guards.ts

@@ -0,0 +1,155 @@
+import type { BaseComponent } from "../components";
+import type ArcheType from "../ArcheType";
+import type { LifecycleEvent } from "../events/EntityLifecycleEvents";
+import type { ComponentTargetConfig } from "./registry";
+import { typeIdOfCtor } from "./registry";
+
+/**
+ * Check if an event matches the component targeting configuration
+ */
+export function matchesComponentTarget(event: LifecycleEvent, componentTarget?: ComponentTargetConfig): boolean {
+    // If no component targeting is specified, always match
+    if (!componentTarget) {
+        return true;
+    }
+
+    const entity = event.getEntity();
+    const entityComponents = entity.componentList();
+
+    // Check archetype matching first (most specific)
+    if (componentTarget.archetype) {
+        if (!matchesArchetype(entityComponents, componentTarget.archetype, !!(componentTarget.includeComponents?.length || componentTarget.excludeComponents?.length))) {
+            return false;
+        }
+    }
+
+    // Check multiple archetypes (OR logic)
+    if (componentTarget.archetypes && componentTarget.archetypes.length > 0) {
+        const allowExtra = !!(componentTarget.includeComponents?.length || componentTarget.excludeComponents?.length);
+        const matchesAnyArchetype = componentTarget.archetypes.some(archetype =>
+            matchesArchetype(entityComponents, archetype, allowExtra)
+        );
+        if (!matchesAnyArchetype) {
+            return false;
+        }
+    }
+
+    // Check included components
+    if (componentTarget.includeComponents && componentTarget.includeComponents.length > 0) {
+        const includeMatch = checkComponentPresence(
+            entityComponents,
+            componentTarget.includeComponents,
+            componentTarget.requireAllIncluded ?? true
+        );
+
+        if (!includeMatch) {
+            return false;
+        }
+    }
+
+    // Check excluded components
+    if (componentTarget.excludeComponents && componentTarget.excludeComponents.length > 0) {
+        const excludeMatch = checkComponentAbsence(
+            entityComponents,
+            componentTarget.excludeComponents,
+            componentTarget.requireAllExcluded ?? true
+        );
+
+        if (!excludeMatch) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Check if required components are present on the entity
+ */
+export function checkComponentPresence(
+    entityComponents: BaseComponent[],
+    requiredComponents: (new () => BaseComponent)[],
+    requireAll: boolean
+): boolean {
+    const entityComponentTypes = new Set(
+        entityComponents.map(comp => comp.getTypeID())
+    );
+
+    const requiredTypeIds = requiredComponents.map(typeIdOfCtor);
+
+    if (requireAll) {
+        // ALL required components must be present (AND logic)
+        return requiredTypeIds.every(typeId => entityComponentTypes.has(typeId));
+    } else {
+        // ANY required component must be present (OR logic)
+        return requiredTypeIds.some(typeId => entityComponentTypes.has(typeId));
+    }
+}
+
+/**
+ * Check if excluded components are absent from the entity
+ */
+export function checkComponentAbsence(
+    entityComponents: BaseComponent[],
+    excludedComponents: (new () => BaseComponent)[],
+    requireAll: boolean
+): boolean {
+    const entityComponentTypes = new Set(
+        entityComponents.map(comp => comp.getTypeID())
+    );
+
+    const excludedTypeIds = excludedComponents.map(typeIdOfCtor);
+
+    if (requireAll) {
+        // ALL excluded components must be absent (AND logic)
+        return excludedTypeIds.every(typeId => !entityComponentTypes.has(typeId));
+    } else {
+        // ANY excluded component must be absent (OR logic) - this is less common but supported
+        return excludedTypeIds.some(typeId => !entityComponentTypes.has(typeId));
+    }
+}
+
+/**
+ * Check if entity components match a specific archetype
+ */
+export function matchesArchetype(entityComponents: BaseComponent[], archetype: ArcheType, allowExtraComponents: boolean = false): boolean {
+    // Get the expected component types from the archetype
+    // We need to access the private componentMap from ArcheType
+    const archetypeComponentMap = (archetype as any).componentMap as Record<string, typeof BaseComponent>;
+
+    if (!archetypeComponentMap) {
+        return false;
+    }
+
+    const expectedComponentTypes = new Set(
+        Object.values(archetypeComponentMap).map(compCtor => typeIdOfCtor(compCtor as any))
+    );
+
+    const entityComponentTypes = new Set(
+        entityComponents.map(comp => comp.getTypeID())
+    );
+
+    if (allowExtraComponents) {
+        // Entity must have at least all the component types from the archetype
+        // (allows additional components beyond the archetype)
+        for (const expectedType of expectedComponentTypes) {
+            if (!entityComponentTypes.has(expectedType)) {
+                return false;
+            }
+        }
+        return true;
+    } else {
+        // Entity must have exactly the same component types as the archetype
+        if (expectedComponentTypes.size !== entityComponentTypes.size) {
+            return false;
+        }
+
+        // All expected component types must be present in the entity
+        for (const expectedType of expectedComponentTypes) {
+            if (!entityComponentTypes.has(expectedType)) {
+                return false;
+            }
+        }
+        return true;
+    }
+}

package/core/hooks/registry.ts

@@ -0,0 +1,247 @@
+import type { BaseComponent } from "../components";
+import type ArcheType from "../ArcheType";
+import type { EntityEvent, ComponentEvent, LifecycleEvent } from "../events/EntityLifecycleEvents";
+import { getMetadataStorage } from "../metadata";
+
+// Memoized constructor → typeId. Hook matching runs on every save event for
+// every hook filter; instantiating components (`new compCtor()`) per check
+// was O(hooks × filters) constructor calls per event.
+const typeIdCache = new Map<Function, string>();
+export function typeIdOfCtor(compCtor: new () => BaseComponent): string {
+    let id = typeIdCache.get(compCtor);
+    if (id === undefined) {
+        id = getMetadataStorage().getComponentId(compCtor.name);
+        typeIdCache.set(compCtor, id);
+    }
+    return id;
+}
+
+/**
+ * Hook callback function signature for entity events
+ */
+export type EntityHookCallback<T extends EntityEvent = EntityEvent> = (event: T) => void;
+
+/**
+ * Hook callback function signature for component events
+ */
+export type ComponentHookCallback<T extends ComponentEvent = ComponentEvent> = (event: T) => void;
+
+/**
+ * Hook callback function signature for any lifecycle event
+ */
+export type LifecycleHookCallback = (event: LifecycleEvent) => void;
+
+/**
+ * Component targeting configuration for hooks
+ */
+export interface ComponentTargetConfig {
+    /** Component types that must be present on the entity for the hook to execute */
+    includeComponents?: (new () => BaseComponent)[];
+    /** Component types that must NOT be present on the entity for the hook to execute */
+    excludeComponents?: (new () => BaseComponent)[];
+    /** Whether to require ALL included components (AND) or ANY included component (OR) */
+    requireAllIncluded?: boolean;
+    /** Whether to require ALL excluded components to be absent (AND) or ANY excluded component to be absent (OR) */
+    requireAllExcluded?: boolean;
+    /** Archetype to match - entity must have exactly these component types */
+    archetype?: ArcheType;
+    /** Archetypes to match - entity must match ANY of these archetypes */
+    archetypes?: ArcheType[];
+}
+
+/**
+ * Hook registration options
+ */
+export interface HookOptions {
+    /** Priority for hook execution order (higher numbers execute first) */
+    priority?: number;
+    /** Optional name for the hook for debugging */
+    name?: string;
+    /** Whether the hook should be executed asynchronously */
+    async?: boolean;
+    /** Filter function to conditionally execute the hook */
+    filter?: (event: LifecycleEvent) => boolean;
+    /** Maximum execution time in milliseconds (for timeout handling) */
+    timeout?: number;
+    /** Component targeting configuration for fine-grained hook execution */
+    componentTarget?: ComponentTargetConfig;
+}
+
+/**
+ * Registered hook information
+ */
+export interface RegisteredHook {
+    callback: LifecycleHookCallback;
+    options: HookOptions;
+    id: string;
+}
+
+/**
+ * Hook execution metrics
+ */
+export interface HookMetrics {
+    totalExecutions: number;
+    totalExecutionTime: number;
+    averageExecutionTime: number;
+    errorCount: number;
+    lastExecutionTime: number;
+}
+
+/**
+ * Registry state owned by the manager instance
+ */
+export interface RegistryState {
+    hooks: Map<string, RegisteredHook[]>;
+    hookCounter: number;
+}
+
+/**
+ * Create initial registry state
+ */
+export function createRegistryState(): RegistryState {
+    return {
+        hooks: new Map(),
+        hookCounter: 0
+    };
+}
+
+/**
+ * Generate a unique hook ID
+ */
+export function generateHookId(state: RegistryState): string {
+    return `hook_${++state.hookCounter}_${Date.now()}`;
+}
+
+/**
+ * Sort hooks by priority (higher priority first)
+ */
+export function sortHooksByPriority(state: RegistryState, eventType: string): void {
+    const hooks = state.hooks.get(eventType);
+    if (hooks) {
+        hooks.sort((a, b) => (b.options.priority || 0) - (a.options.priority || 0));
+    }
+}
+
+/**
+ * Register a hook for entity lifecycle events
+ */
+export function registerEntityHook<T extends EntityEvent>(
+    state: RegistryState,
+    eventType: T['eventType'],
+    callback: EntityHookCallback<T>,
+    options: HookOptions
+): string {
+    const hookId = generateHookId(state);
+    const hook: RegisteredHook = {
+        callback: callback as LifecycleHookCallback,
+        options: { priority: 0, ...options },
+        id: hookId
+    };
+
+    if (!state.hooks.has(eventType)) {
+        state.hooks.set(eventType, []);
+    }
+
+    state.hooks.get(eventType)!.push(hook);
+    sortHooksByPriority(state, eventType);
+
+    return hookId;
+}
+
+/**
+ * Register a hook for component lifecycle events
+ */
+export function registerComponentHook<T extends ComponentEvent>(
+    state: RegistryState,
+    eventType: T['eventType'],
+    callback: ComponentHookCallback<T>,
+    options: HookOptions
+): string {
+    const hookId = generateHookId(state);
+    const hook: RegisteredHook = {
+        callback: callback as LifecycleHookCallback,
+        options: { priority: 0, ...options },
+        id: hookId
+    };
+
+    if (!state.hooks.has(eventType)) {
+        state.hooks.set(eventType, []);
+    }
+
+    state.hooks.get(eventType)!.push(hook);
+    sortHooksByPriority(state, eventType);
+
+    return hookId;
+}
+
+/**
+ * Register a hook for all lifecycle events
+ */
+export function registerLifecycleHook(
+    state: RegistryState,
+    callback: LifecycleHookCallback,
+    options: HookOptions
+): string {
+    const hookId = generateHookId(state);
+    const hook: RegisteredHook = {
+        callback,
+        options: { priority: 0, ...options },
+        id: hookId
+    };
+
+    // Register for all event types
+    const allEventTypes = [
+        "entity.created", "entity.updated", "entity.deleted",
+        "component.added", "component.updated", "component.removed"
+    ];
+
+    for (const eventType of allEventTypes) {
+        if (!state.hooks.has(eventType)) {
+            state.hooks.set(eventType, []);
+        }
+        state.hooks.get(eventType)!.push({ ...hook }); // Clone hook for each event type
+    }
+
+    return hookId;
+}
+
+/**
+ * Remove a hook by its ID
+ */
+export function removeHook(state: RegistryState, hookId: string): boolean {
+    let removed = false;
+
+    for (const [eventType, hooks] of state.hooks.entries()) {
+        const initialLength = hooks.length;
+        state.hooks.set(eventType, hooks.filter(hook => hook.id !== hookId));
+
+        if (state.hooks.get(eventType)!.length < initialLength) {
+            removed = true;
+        }
+    }
+
+    return removed;
+}
+
+/**
+ * Get the number of registered hooks for an event type
+ */
+export function getHookCount(state: RegistryState, eventType?: string): number {
+    if (eventType) {
+        return state.hooks.get(eventType)?.length || 0;
+    }
+
+    let total = 0;
+    for (const hooks of state.hooks.values()) {
+        total += hooks.length;
+    }
+    return total;
+}
+
+/**
+ * Clear all hooks
+ */
+export function clearAllHooks(state: RegistryState): void {
+    state.hooks.clear();
+    state.hookCounter = 0;
+}

package/core/metadata/definitions/Component.ts

@@ -20,6 +20,6 @@ export interface ComponentPropertyMetadata {
 export interface IndexedFieldMetadata {
     componentId: string;
     propertyKey: string;
-    indexType: 'gin' | 'btree' | 'hash' | 'numeric';
+    indexType: 'gin' | 'btree' | 'hash' | 'numeric' | 'fulltext';
     isDateField: boolean;
 }

package/core/metadata/index.ts

@@ -3,6 +3,11 @@ import { getMetadataStorage } from "./getMetadataStorage";
 
 export { getMetadataStorage } from "./getMetadataStorage";
 
+// Cached after first call — metadata is fixed after startup so serialization
+// cost is paid only once regardless of how many /studio navigations occur.
+let _metadataCache: ReturnType<typeof getSerializedMetadataStorage> | undefined;
+let _metadataScriptCache: string | undefined;
+
 function toFieldLabel(fieldName: string): string {
     let label = fieldName.replace(/_/g, ' ');
     label = label.split(' ').map(word => word === 'id' ? 'ID' : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join(' ');
@@ -20,6 +25,8 @@ export function getSerializedMetadataStorage(): {
         }[]
     >;
 } {
+    if (_metadataCache) return _metadataCache;
+
     const storage = getMetadataStorage();
     const archeTypes: Record<string, any> = {};
 
@@ -34,11 +41,15 @@ export function getSerializedMetadataStorage(): {
         });
     });
 
-    // console.log(archeTypes, 'archeTypes');
+    _metadataCache = { archeTypes };
+    return _metadataCache;
+}
 
-    return {
-        archeTypes,
-    };
+/** Returns the pre-serialized `<script>` tag for studio injection. */
+export function getMetadataScript(): string {
+    if (_metadataScriptCache) return _metadataScriptCache;
+    _metadataScriptCache = `<script>window.bunsaneMetadata = ${JSON.stringify(getSerializedMetadataStorage())};</script>`;
+    return _metadataScriptCache;
 }
 
 export function Enum() {

package/core/middleware/RateLimit.ts

@@ -1,105 +1,102 @@
-import type { Middleware } from '../Middleware';
-import { logger as MainLogger } from '../Logger';
-
-const logger = MainLogger.child({ scope: 'RateLimit' });
-
-export type RateLimitOptions = {
-    /** Maximum requests in the window. Default: 100 */
-    max?: number;
-    /** Window length in milliseconds. Default: 60_000 (1 min) */
-    windowMs?: number;
-    /** Only apply to paths matching this prefix list. Default: all */
-    pathPrefixes?: string[];
-    /** Extract client key (override default: X-Forwarded-For → remote). */
-    keyExtractor?: (req: Request) => string;
-    /** Response status for rejection. Default: 429 */
-    status?: number;
-    /** Trust X-Forwarded-For header. Default: false */
-    trustProxy?: boolean;
-};
-
-type Bucket = {
-    count: number;
-    resetAt: number;
-};
-
-/**
- * In-memory token-bucket rate limiter. Per-instance only — for multi-instance
- * deployments use a shared Redis-backed limiter. Sweeps expired buckets on
- * each increment to keep memory bounded.
- */
-export function rateLimit(options: RateLimitOptions = {}): Middleware {
-    const max = options.max ?? 100;
-    const windowMs = options.windowMs ?? 60_000;
-    const pathPrefixes = options.pathPrefixes;
-    const status = options.status ?? 429;
-    const trustProxy = options.trustProxy ?? false;
-    const keyExtractor = options.keyExtractor ?? ((req: Request) => {
-        if (trustProxy) {
-            const xff = req.headers.get('x-forwarded-for');
-            if (xff) return xff.split(',')[0]!.trim();
-        }
-        const realIp = req.headers.get('x-real-ip');
-        if (realIp) return realIp;
-        return 'anonymous';
-    });
-
-    const buckets = new Map<string, Bucket>();
-    let lastSweep = Date.now();
-
-    return async (req, next) => {
-        if (pathPrefixes && pathPrefixes.length > 0) {
-            const url = new URL(req.url);
-            const match = pathPrefixes.some((p) => url.pathname.startsWith(p));
-            if (!match) return next();
-        }
-
-        const now = Date.now();
-        const key = keyExtractor(req);
-
-        if (now - lastSweep > windowMs) {
-            for (const [k, v] of buckets) {
-                if (v.resetAt <= now) buckets.delete(k);
-            }
-            lastSweep = now;
-        }
-
-        let bucket = buckets.get(key);
-        if (!bucket || bucket.resetAt <= now) {
-            bucket = { count: 0, resetAt: now + windowMs };
-            buckets.set(key, bucket);
-        }
-
-        bucket.count++;
-        const remaining = Math.max(0, max - bucket.count);
-        const retryAfterSec = Math.ceil((bucket.resetAt - now) / 1000);
-
-        if (bucket.count > max) {
-            logger.warn({ key, path: new URL(req.url).pathname, count: bucket.count, max }, 'rate limit exceeded');
-            return new Response(
-                JSON.stringify({ error: 'Too many requests', retryAfter: retryAfterSec }),
-                {
-                    status,
-                    headers: {
-                        'Content-Type': 'application/json',
-                        'Retry-After': String(retryAfterSec),
-                        'X-RateLimit-Limit': String(max),
-                        'X-RateLimit-Remaining': '0',
-                        'X-RateLimit-Reset': String(Math.floor(bucket.resetAt / 1000)),
-                    },
-                },
-            );
-        }
-
-        const response = await next();
-        const newHeaders = new Headers(response.headers);
-        newHeaders.set('X-RateLimit-Limit', String(max));
-        newHeaders.set('X-RateLimit-Remaining', String(remaining));
-        newHeaders.set('X-RateLimit-Reset', String(Math.floor(bucket.resetAt / 1000)));
-        return new Response(response.body, {
-            status: response.status,
-            statusText: response.statusText,
-            headers: newHeaders,
-        });
-    };
-}
+import type { Middleware } from '../Middleware';
+import { logger as MainLogger } from '../Logger';
+import { setResponseHeaders } from './headers';
+
+const logger = MainLogger.child({ scope: 'RateLimit' });
+
+export type RateLimitOptions = {
+    /** Maximum requests in the window. Default: 100 */
+    max?: number;
+    /** Window length in milliseconds. Default: 60_000 (1 min) */
+    windowMs?: number;
+    /** Only apply to paths matching this prefix list. Default: all */
+    pathPrefixes?: string[];
+    /** Extract client key (override default: X-Forwarded-For → remote). */
+    keyExtractor?: (req: Request) => string;
+    /** Response status for rejection. Default: 429 */
+    status?: number;
+    /** Trust X-Forwarded-For header. Default: false */
+    trustProxy?: boolean;
+};
+
+type Bucket = {
+    count: number;
+    resetAt: number;
+};
+
+/**
+ * In-memory token-bucket rate limiter. Per-instance only — for multi-instance
+ * deployments use a shared Redis-backed limiter. Sweeps expired buckets on
+ * each increment to keep memory bounded.
+ */
+export function rateLimit(options: RateLimitOptions = {}): Middleware {
+    const max = options.max ?? 100;
+    const windowMs = options.windowMs ?? 60_000;
+    const pathPrefixes = options.pathPrefixes;
+    const status = options.status ?? 429;
+    const trustProxy = options.trustProxy ?? false;
+    const keyExtractor = options.keyExtractor ?? ((req: Request) => {
+        if (trustProxy) {
+            const xff = req.headers.get('x-forwarded-for');
+            if (xff) return xff.split(',')[0]!.trim();
+        }
+        const realIp = req.headers.get('x-real-ip');
+        if (realIp) return realIp;
+        return 'anonymous';
+    });
+
+    const buckets = new Map<string, Bucket>();
+    let lastSweep = Date.now();
+
+    return async (req, next) => {
+        if (pathPrefixes && pathPrefixes.length > 0) {
+            const url = new URL(req.url);
+            const match = pathPrefixes.some((p) => url.pathname.startsWith(p));
+            if (!match) return next();
+        }
+
+        const now = Date.now();
+        const key = keyExtractor(req);
+
+        if (now - lastSweep > windowMs) {
+            for (const [k, v] of buckets) {
+                if (v.resetAt <= now) buckets.delete(k);
+            }
+            lastSweep = now;
+        }
+
+        let bucket = buckets.get(key);
+        if (!bucket || bucket.resetAt <= now) {
+            bucket = { count: 0, resetAt: now + windowMs };
+            buckets.set(key, bucket);
+        }
+
+        bucket.count++;
+        const remaining = Math.max(0, max - bucket.count);
+        const retryAfterSec = Math.ceil((bucket.resetAt - now) / 1000);
+
+        if (bucket.count > max) {
+            logger.warn({ key, path: new URL(req.url).pathname, count: bucket.count, max }, 'rate limit exceeded');
+            return new Response(
+                JSON.stringify({ error: 'Too many requests', retryAfter: retryAfterSec }),
+                {
+                    status,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Retry-After': String(retryAfterSec),
+                        'X-RateLimit-Limit': String(max),
+                        'X-RateLimit-Remaining': '0',
+                        'X-RateLimit-Reset': String(Math.floor(bucket.resetAt / 1000)),
+                    },
+                },
+            );
+        }
+
+        const response = await next();
+        return setResponseHeaders(response, [
+            ['X-RateLimit-Limit', String(max)],
+            ['X-RateLimit-Remaining', String(remaining)],
+            ['X-RateLimit-Reset', String(Math.floor(bucket.resetAt / 1000))],
+        ]);
+    };
+}