yeow-api 0.2.30 → 0.2.31

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "yeow-api",
-    "version": "0.2.30",
+    "version": "0.2.31",
     "description": "Yeow API �?TypeScript OOP wrappers over the task protocol",
     "type": "module",
     "main": "./src/index.ts",

package/src/command.ts

@@ -13,14 +13,19 @@ export interface CommandPayload {
     readonly label: string;
 }
 
+type CompleterFn = (sender: CommandSender, args: string[]) => string[];
+export interface ManualCompleter {
+    manualRelease: true;
+    handler: (sender: CommandSender, args: string[], release: (result: string[]) => void) => void;
+}
+
 export interface CommandOptions {
     description?: string;
     usage?: string;
     permission?: string;
     aliases?: string[];
     executor: (payload: CommandPayload) => void;
-    /** Optional tab completer. Receives (sender, args) and returns completion suggestions. */
-    completer?: (sender: CommandSender, args: string[]) => string[];
+    completer?: CompleterFn | ManualCompleter;
 }
 
 export function registerCommand(name: string, options: CommandOptions): boolean {
@@ -40,8 +45,30 @@ export function registerCommand(name: string, options: CommandOptions): boolean
 
     let compCbId = '';
     if (completer) {
-        compCbId = (globalThis as any)._registerCallback((data: any) => {
-            return completer(data.sender, data.args);
+        let manualRelease = false;
+        let completerFn: Function;
+        if (typeof completer === 'object' && (completer as any).manualRelease) {
+            manualRelease = true;
+            completerFn = (completer as any).handler;
+        } else {
+            completerFn = completer as CompleterFn;
+        }
+
+        compCbId = (globalThis as any)._registerCallback((data: any, release: Function) => {
+            try {
+                if (manualRelease) {
+                    completerFn(data.sender, data.args, release);
+                } else {
+                    const result = completerFn(data.sender, data.args);
+                    if (result && typeof result.then === 'function') {
+                        release([]);  // async → release immediate, use ManualCompleter for async
+                    } else {
+                        release(result || []);
+                    }
+                }
+            } catch (e) {
+                release([]);
+            }
         }, { persistent: true });
     }
 

package/src/event.ts

@@ -301,9 +301,20 @@ function adaptEvent(type: string, data: any): any {
 
 // ── EventOn/EventOff ───────────────────────────────────────────────
 
-export function eventOn<K extends keyof EventMap>(eventType: K, handler: (e: EventMap[K]) => void): () => void {
-    const wrapper = (data: any) => handler(data as EventMap[K]);
+export function eventOn<K extends keyof EventMap>(
+    eventType: K,
+    handler: ((e: EventMap[K]) => void) | ((e: EventMap[K], release: (result?: any) => void) => void),
+    options?: { manualRelease?: boolean }
+): () => void {
+    const wrapper = (data: any, release?: Function) => {
+        if (options?.manualRelease) {
+            (handler as any)(data as EventMap[K], release);
+        } else {
+            (handler as any)(data as EventMap[K]);
+        }
+    };
     (wrapper as any)._raw = handler;
+    (wrapper as any)._manualRelease = !!options?.manualRelease;
 
     if (!(globalThis as any).__yeowEventHandlers) (globalThis as any).__yeowEventHandlers = {};
     if (!(globalThis as any).__yeowEventHandlers[eventType]) {
@@ -333,16 +344,14 @@ export function eventOff(eventType: string, handler: Function): void {
 
 // ── _onEvent dispatcher (called from init.js) ──────────────────────
 
-(globalThis as any)._onEvent = (eventType: string, data: any): any => {
+(globalThis as any)._onEvent = (eventType: string, data: any, release: Function): void => {
     const handlers = (globalThis as any).__yeowEventHandlers?.[eventType];
-    if (!handlers?.length) return {};
+    if (!handlers?.length) { release({}); return; }
 
     const cancellable = data?._cancellable;
-    const mods: Record<string, any> = {};
-
     const wrapped = adaptEvent(eventType, data);
-
     const localMods: Record<string, any> = {};
+
     if (cancellable) {
         Object.defineProperty(wrapped, 'cancelled', {
             get: () => localMods.cancelled || false,
@@ -351,9 +360,24 @@ export function eventOff(eventType: string, handler: Function): void {
         });
     }
 
-    for (const handler of handlers) {
+    const finish = () => {
+        if (cancellable && localMods.cancelled) release({ cancelled: true });
+        else release({});
+    };
+
+    for (const wrapper of handlers) {
         try {
-            handler(wrapped);
+            if ((wrapper as any)._manualRelease) {
+                wrapper(wrapped, release);
+                return;
+            }
+            const result = wrapper(wrapped);
+            if (result && typeof result.then === 'function') {
+                // Async handler — release immediately with sync mods only.
+                // Awaiting async operations in event handlers requires manualRelease: true.
+                finish();
+                return;
+            }
         } catch (e: any) {
             const errInfo: any = {
                 message: e?.message || String(e),
@@ -369,6 +393,6 @@ export function eventOff(eventType: string, handler: Function): void {
             (globalThis as any).$send('reportError', errInfo);
         }
     }
-    if (cancellable && localMods.cancelled) mods.cancelled = true;
-    return mods;
+
+    finish();
 };

package/src/index.ts

@@ -6,7 +6,7 @@ export { Entity, LivingEntity } from './entity.js';
 export { Block } from './block.js';
 export { Inventory } from './inventory.js';
 export { registerCommand } from './command.js';
-export type { CommandOptions, CommandPayload, CommandSender } from './command.js';
+export type { CommandOptions, CommandPayload, CommandSender, ManualCompleter } from './command.js';
 export { eventOn, eventOff } from './event.js';
 export type {
     PlayerJoinEvent, PlayerQuitEvent, PlayerChatEvent, PlayerMoveEvent,