yeow-api 0.3.0 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "yeow-api",
-    "version": "0.3.0",
+    "version": "0.3.5",
     "description": "Yeow API",
     "type": "module",
     "main": "./src/index.ts",

package/src/command.ts

@@ -79,23 +79,13 @@ export function registerCommand(name: string, options: CommandOptions, taskOptio
         } else {
           const result = completerFn(sender, data.args);
           if (result && typeof result.then === 'function') {
-            // 异步 completer：await 结果后再回传（原实现立即发空补全、Promise 结果被丢弃）
-            (result as Promise<string[]>).then(
-              (list) => {
-                $send('task', {
-                  type: 'command.tabComplete',
-                  params: { callbackId: compCbId, completions: list || [] },
-                  cb: '',
-                });
-              },
-              () => {
-                $send('task', {
-                  type: 'command.tabComplete',
-                  params: { callbackId: compCbId, completions: [] },
-                  cb: '',
-                });
-              },
-            );
+            // 自动模式不等待 Promise（与事件处理一致）：收到 Promise 视为无补全，
+            // 立即释放（空补全）；异步补全请使用手动模式 complete(res)
+            $send('task', {
+              type: 'command.tabComplete',
+              params: { callbackId: compCbId, completions: [] },
+              cb: '',
+            });
           } else {
             $send('task', {
               type: 'command.tabComplete',

package/src/core.ts

@@ -103,3 +103,9 @@ export { registerPermission } from './permission.js';
 export type { Permission, PermissionOptions, PermissionDefault } from './permission.js';
 export { createWorker, Worker, onMessage, postMessage } from './worker.js';
 export type { WorkerOptions } from './worker.js';
+export {
+    stringToBytes, stringToBytesAsync,
+    bytesToString, bytesToStringAsync,
+    gzipCompress, gzipCompressSync,
+    gzipDecompress, gzipDecompressSync,
+} from './util.js';

package/src/event.ts

@@ -358,11 +358,12 @@ function loc(raw: Record<string, unknown> | null): Location | null {
   );
 }
 
-function adaptEvent<K extends keyof EventMap>(type: K, data: RawEvent): EventMap[K] {
-  const wrap: Record<string, unknown> = {};
+function adaptEvent<K extends keyof EventMap>(type: K, data: RawEvent): { event: EventMap[K]; mods: Record<string, unknown> } {
+  // 初始值：原始数据（跳过 _ 前缀内部字段），player/from/to/respawnLocation 适配为对象
+  const initial: Record<string, unknown> = {};
   for (const key of Object.keys(data)) {
     if (key.startsWith('_')) continue;
-    wrap[key] = data[key];
+    initial[key] = data[key];
   }
   const hasPlayer = [
     'playerJoin', 'playerQuit', 'playerChat', 'playerMove',
@@ -375,13 +376,34 @@ function adaptEvent<K extends keyof EventMap>(type: K, data: RawEvent): EventMap
     'playerAdvancementDone', 'playerToggleSneak', 'playerToggleFlight',
     'inventoryClick', 'playerResourcePackStatus',
   ] as K[];
-  if (hasPlayer.includes(type) && data.player) {
-    wrap.player = Player.getSync(data.player as string);
+  // 直接以 uuid 构造 Player（零往返）；name 在首次访问时惰性获取（见 Player.name）
+  if (hasPlayer.includes(type) && data.player) initial.player = new Player(data.player as string);
+  if (data.from) initial.from = loc(data.from as Record<string, unknown>);
+  if (data.to) initial.to = loc(data.to as Record<string, unknown>);
+  if (data.respawnLocation) initial.respawnLocation = loc(data.respawnLocation as Record<string, unknown>);
+
+  // 修改收集：所有字段经 getter/setter——handler 直接赋值（e.xxx = ...）即记录为回写 mods。
+  // cancelled 单独处理（仅可取消事件暴露；读取语义保持原状：未设置时返回 false）。
+  const mods: Record<string, unknown> = {};
+  const wrap: Record<string, unknown> = {};
+  for (const key of Object.keys(initial)) {
+    if (key === 'cancelled') continue;
+    Object.defineProperty(wrap, key, {
+      get: () => (key in mods ? mods[key] : initial[key]),
+      set: (v: unknown) => { mods[key] = v; },
+      enumerable: true,
+      configurable: true,
+    });
   }
-  if (data.from) wrap.from = loc(data.from as Record<string, unknown>);
-  if (data.to) wrap.to = loc(data.to as Record<string, unknown>);
-  if (data.respawnLocation) wrap.respawnLocation = loc(data.respawnLocation as Record<string, unknown>);
-  return wrap as unknown as EventMap[K];
+  if (data._cancellable) {
+    Object.defineProperty(wrap, 'cancelled', {
+      get: () => (mods.cancelled as boolean) || false,
+      set: (v: boolean) => { mods.cancelled = v; },
+      enumerable: true,
+      configurable: true,
+    });
+  }
+  return { event: wrap as unknown as EventMap[K], mods };
 }
 
 // ── Event Subscription ─────────────────────────────────────────────
@@ -411,18 +433,8 @@ export function eventOn<K extends keyof EventMap>(
   const pluginName = __plugin?.name || 'unknown';
 
   const cbId = _registerCallback((data: RawEvent) => {
-    const wrapped = adaptEvent(eventType, data);
+    const { event: wrapped, mods: mutatedMods } = adaptEvent(eventType, data);
     const eventId = data?._eventId;
-    const cancellable = data?._cancellable;
-    const localMods: { cancelled?: boolean } = {};
-
-    if (cancellable) {
-      Object.defineProperty(wrapped, 'cancelled', {
-        get: () => localMods.cancelled || false,
-        set: (v: boolean) => { localMods.cancelled = v; },
-        enumerable: true,
-      });
-    }
 
     if (manualRelease) {
       const complete = (result?: Record<string, unknown>) => {
@@ -437,10 +449,12 @@ export function eventOn<K extends keyof EventMap>(
     }
 
     const result = (handler as EventHandler<typeof eventType>)(wrapped);
+    // 回写合并：返回值（mods）优先合并，事件参数直接赋值（e.xxx = ...）覆盖之——
+    // 返回 Promise 时视为无修改（Promise 不展开），事件立即释放
     const mods: Record<string, unknown> = {
       ...(result && typeof result === 'object' ? result : {}),
+      ...mutatedMods,
     };
-    if (localMods.cancelled) mods.cancelled = true;
     $send('task', { type: 'event.complete', params: { eventId, mods }, cb: '' });
   }, { persistent: true });
 

package/src/player.ts

@@ -32,7 +32,15 @@ export class Player {
 
   constructor(public readonly uuid: string, private _name?: string) {}
 
-  get name(): string { return this._name ?? ''; }
+  /** 玩家名。未提供时首次访问惰性同步获取并缓存（仅一次往返）。 */
+  get name(): string {
+    if (this._name === undefined) {
+      let n = '';
+      try { n = call<PlayerData>('player.get', { identifier: this.uuid })?.name ?? ''; } catch { /* 离线/异常 → '' */ }
+      this._name = n;
+    }
+    return this._name;
+  }
 
   /** 玩家物品栏（统一 Inventory 容器抽象）。 */
   get inventory(): Inventory {

package/src/util.ts

@@ -0,0 +1,77 @@
+// util 通道：gzip 压缩/解压 + UTF-8 ↔ 字节转换。
+//
+// 协议层字节数据以 base64 字符串承载（引擎原生 Uint8Array.toBase64()/fromBase64()
+// 负责转换）——本模块输入输出一律 Uint8Array / string，**不暴露 base64**。
+// encode/decode 的语义是 buffer ↔ 字符串；无流式接口（一次性整体处理）。
+
+/** util 通道同步调用：err → 抛 Error。 */
+function send<T>(t: string, p: Record<string, unknown>): T {
+  const r = $send('util', { t, p }) as T | { err?: string } | null;
+  if (r == null) return undefined as T;
+  if ((r as { err?: string }).err) throw new Error((r as { err?: string }).err);
+  return r as T;
+}
+
+/** util 通道异步调用（ioExecutor 上执行，不阻塞 JS 线程）。 */
+function sendAsync<T>(t: string, p: Record<string, unknown>): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const cbId = _registerCallback((r: T | { err?: string }) => {
+      if ((r as { err?: string })?.err) reject(new Error((r as { err?: string }).err));
+      else resolve(r as T);
+    });
+    $send('util', { t, p, cb: cbId });
+  });
+}
+
+/** 输入规范化：string 视为 UTF-8 文本（经 encode.utf8 字节化）；Uint8Array 直接转换。 */
+function toB64(data: Uint8Array | string): string {
+  return typeof data === 'string'
+    ? send<{ data: string }>('encode.utf8', { data }).data
+    : data.toBase64();
+}
+
+// ── 字符串 ↔ 字节（UTF-8）────────────────────────────────────────
+
+/** UTF-8 字符串 → 字节（同步）。 */
+export function stringToBytes(text: string): Uint8Array {
+  return Uint8Array.fromBase64(send<{ data: string }>('encode.utf8', { data: text }).data);
+}
+
+/** 字节 → UTF-8 字符串（同步；非法序列替换为 U+FFFD，不抛错）。 */
+export function bytesToString(bytes: Uint8Array): string {
+  return send<{ data: string }>('decode.utf8', { data: bytes.toBase64() }).data;
+}
+
+/** UTF-8 字符串 → 字节（异步，ioExecutor 执行）。 */
+export function stringToBytesAsync(text: string): Promise<Uint8Array> {
+  return sendAsync<{ data: string }>('encode.utf8', { data: text }).then((r) => Uint8Array.fromBase64(r.data));
+}
+
+/** 字节 → UTF-8 字符串（异步）。 */
+export function bytesToStringAsync(bytes: Uint8Array): Promise<string> {
+  return sendAsync<{ data: string }>('decode.utf8', { data: bytes.toBase64() }).then((r) => r.data);
+}
+
+// ── gzip ──────────────────────────────────────────────────────────
+
+/** gzip 压缩（level 0-9，默认引擎默认级别）。输入 string 视为 UTF-8 文本。 */
+export function gzipCompress(data: Uint8Array | string, level?: number): Promise<Uint8Array> {
+  return sendAsync<{ data: string }>('gzip.compress', { data: toB64(data), level })
+    .then((r) => Uint8Array.fromBase64(r.data));
+}
+
+/** gzip 压缩（同步版）。 */
+export function gzipCompressSync(data: Uint8Array | string, level?: number): Uint8Array {
+  return Uint8Array.fromBase64(send<{ data: string }>('gzip.compress', { data: toB64(data), level }).data);
+}
+
+/** gzip 解压（输出上限 256 MiB，超限报错——防压缩炸弹）。 */
+export function gzipDecompress(data: Uint8Array | string): Promise<Uint8Array> {
+  return sendAsync<{ data: string }>('gzip.decompress', { data: toB64(data) })
+    .then((r) => Uint8Array.fromBase64(r.data));
+}
+
+/** gzip 解压（同步版）。 */
+export function gzipDecompressSync(data: Uint8Array | string): Uint8Array {
+  return Uint8Array.fromBase64(send<{ data: string }>('gzip.decompress', { data: toB64(data) }).data);
+}