bunsane 0.3.2 → 0.4.0

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))],
+        ]);
+    };
+}

package/core/middleware/RequestId.ts

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from 'async_hooks';
 import type { Middleware } from '../Middleware';
+import { setResponseHeaders } from './headers';
 
 /**
  * AsyncLocalStorage to propagate requestId to any code running within a request.
@@ -24,15 +25,7 @@ export function requestId(): Middleware {
 
         return requestStore.run({ requestId: id }, async () => {
             const response = await next();
-
-            const newHeaders = new Headers(response.headers);
-            newHeaders.set('X-Request-Id', id);
-
-            return new Response(response.body, {
-                status: response.status,
-                statusText: response.statusText,
-                headers: newHeaders,
-            });
+            return setResponseHeaders(response, [['X-Request-Id', id]]);
         });
     };
 }

package/core/middleware/SecurityHeaders.ts

@@ -1,4 +1,5 @@
 import type { Middleware } from '../Middleware';
+import { setResponseHeaders } from './headers';
 
 export type SecurityHeadersOptions = {
     /** Enable HSTS header. Default: true in production */
@@ -47,16 +48,6 @@ export function securityHeaders(options: SecurityHeadersOptions = {}): Middlewar
 
     return async (req, next) => {
         const response = await next();
-
-        const newHeaders = new Headers(response.headers);
-        for (const [key, value] of headersToSet) {
-            newHeaders.set(key, value);
-        }
-
-        return new Response(response.body, {
-            status: response.status,
-            statusText: response.statusText,
-            headers: newHeaders,
-        });
+        return setResponseHeaders(response, headersToSet);
     };
 }

package/core/middleware/headers.ts

@@ -0,0 +1,28 @@
+/**
+ * Attempt to mutate `response.headers` in-place.
+ * Constructed Responses (Yoga, REST handlers) allow mutation; only proxied
+ * fetch Responses guard their headers as immutable. Fall back to a single
+ * clone so the chain never needs more than one new Response.
+ */
+export function setResponseHeaders(
+    response: Response,
+    headers: Iterable<[string, string]>,
+): Response {
+    try {
+        for (const [key, value] of headers) {
+            response.headers.set(key, value);
+        }
+        return response;
+    } catch {
+        // Immutable guard hit (e.g. proxied fetch Response) — clone once.
+        const cloned = new Headers(response.headers);
+        for (const [key, value] of headers) {
+            cloned.set(key, value);
+        }
+        return new Response(response.body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: cloned,
+        });
+    }
+}