@zhin.js/core 1.0.0 → 1.0.1

package/src/types.ts

@@ -1,36 +1,79 @@
 import {MaybePromise}from '@zhin.js/types'
+import {MessageChannel} from "./message.js";
+import {Adapter} from "./adapter.js";
+import {Bot,BotConfig} from "./bot.js";
+import { Databases,Registry } from "@zhin.js/database";
 
-export interface MessageSegment<T extends keyof Segment=keyof Segment> {
-  type: T;
-  data: Segment[T];
+/**
+ * 类型定义文件：包含适配器、消息、数据库、配置等核心类型声明。
+ * 协作者可通过本文件了解各主要数据结构的用途与关系。
+ */
+declare module '@zhin.js/types'{
+  interface GlobalContext extends RegisteredAdapters{}
 }
-export interface Segment{
-  [key:string]:Record<string, any>
-  any:Record<string, any>
+/**
+ * 所有已注册适配器的类型映射（key为适配器名，value为Adapter实例）
+ */
+export interface RegisteredAdapters extends Record<string, Adapter>{}
+/**
+ * 数据库配置类型，支持多种数据库驱动
+ */
+export type DatabaseConfig<T extends keyof Databases=keyof Databases>={
+  dialect:T
+} & Registry.Config<Databases[T]>
+/**
+ * 获取对象所有value类型
+ */
+export type ObjectItem<T extends object>=T[keyof T]
+/**
+ * 已注册适配器名类型
+ */
+export type RegisteredAdapter=keyof RegisteredAdapters
+/**
+ * 指定适配器的消息类型
+ */
+export type AdapterMessage<T extends keyof RegisteredAdapters=keyof RegisteredAdapters>=RegisteredAdapters[T] extends Adapter<infer R>?BotMessage<R>:{}
+/**
+ * 指定适配器的配置类型
+ */
+export type AdapterConfig<T extends keyof RegisteredAdapters=keyof RegisteredAdapters>=RegisteredAdapters[T] extends Adapter<infer R>?PlatformConfig<R>:BotConfig
+/**
+ * Bot实例的配置类型
+ */
+export type PlatformConfig<T>=T extends Bot<infer L,infer R>?R:BotConfig
+/**
+ * Bot实例的消息类型
+ */
+export type BotMessage<T extends Bot>=T extends Bot<infer R>?R:{}
+/**
+ * 消息段结构，支持 text/image/at/face 等类型
+ */
+export interface MessageSegment {
+  type: string;
+  data: Record<string, any>;
 }
+/**
+ * 单个或数组类型
+ */
 export type MaybeArray<T>=T|T[]
+/**
+ * 消息发送内容类型
+ */
 export type SendContent=MaybeArray<string|MessageSegment>
+/**
+ * 消息发送者信息
+ */
 export interface MessageSender{
   id: string;
   name?: string;
 }
-export type MessageComponent<T extends object>=(props:T&{children:SendContent})=>MaybePromise<SendContent>
-export interface MessageChannel{
-  id: string;
-  type: 'group' | 'private' | 'channel';
-}
-export interface Message {
-  id: string;
-  adapter:string
-  bot:string
-  content: MessageSegment[];
-  sender: MessageSender;
-  reply(content:SendContent,quote?:boolean|string):Promise<void>
-  channel: MessageChannel;
-  timestamp: number;
-  raw: string;
-}
-
+/**
+ * 通用字典类型
+ */
+export type Dict<V=any,K extends string|symbol=string>=Record<K, V>;
+/**
+ * 用户信息结构
+ */
 export interface User {
   user_id: string;
   nickname: string;
@@ -38,23 +81,24 @@ export interface User {
   role?: string;
 }
 
+/**
+ * 群组信息结构
+ */
 export interface Group {
   group_id: string;
   group_name: string;
   member_count: number;
 }
 
-export interface BotConfig {
-  name: string;
-  context: string;
-  [key: string]: any;
-}
-
-
 
+/**
+ * App配置类型，涵盖机器人、数据库、插件、调试等
+ */
 export interface AppConfig {
   /** 机器人配置列表 */
   bots?: BotConfig[];
+  /** 数据库配置列表 */
+  database?: DatabaseConfig;
   /** 插件目录列表，默认为 ['./plugins', 'node_modules'] */
   plugin_dirs?: string[];
   /** 需要加载的插件列表 */
@@ -64,6 +108,9 @@ export interface AppConfig {
   /** 是否启用调试模式 */
   debug?: boolean;
 }
+/**
+ * defineConfig辅助类型，支持函数式/对象式配置
+ */
 export type DefineConfig<T> = T | ((env:Record<string,string>)=>MaybePromise<T>);
 
 export interface SendOptions extends MessageChannel{

package/src/utils.ts

@@ -0,0 +1,312 @@
+import {Dict, MessageSegment, SendContent} from "./types";
+
+export function getValueWithRuntime(template: string, ctx: Dict) {
+    const result = evaluate(template, ctx);
+    if (result === `return(${template})`) return undefined;
+    return result;
+}
+export const evaluate = <S, T = any>(exp: string, context: S) => {
+    const result = execute<S, T>(`return(${exp})`, context);
+    // 如果结果是原始表达式，说明访问被阻止，返回 undefined
+    if (result === `return(${exp})`) return undefined;
+    return result;
+};
+const evalCache: Record<string, Function> = Object.create(null);
+export const execute = <S, T = any>(exp: string, context: S):T => {
+    const fn = evalCache[exp] || (evalCache[exp] = toFunction(exp));
+    context={
+        ...context,
+        process:undefined,
+        global:undefined,
+        Buffer:undefined,
+        crypto:undefined
+    }
+    try {
+        return fn.apply(context, [context]);
+    } catch {
+        return exp as T;
+    }
+};
+
+const toFunction = (exp: string): Function => {
+    try {
+        return new Function(`$data`, `with($data){${exp}}`);
+    } catch {
+        return () => {};
+    }
+};
+export function compiler(template: string, ctx: Dict) {
+    const matched = [...template.matchAll(/\${([^}]*?)}/g)];
+    for (const item of matched) {
+        const tpl = item[1];
+        let value = getValueWithRuntime(tpl, ctx);
+        if (value === tpl) continue;
+        if (typeof value !== 'string') value = JSON.stringify(value, null, 2);
+        template = template.replace(`\${${item[1]}}`, value);
+    }
+    return template;
+}
+export function segment<T extends object>(type:string,data:T){
+    return {
+        type,
+        data
+    }
+}
+export namespace segment{
+    export function escape<T>(text: T): T {
+        if (typeof text !== 'string') return text;
+        return text
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&#39;') as T;
+    }
+    export function unescape<T>(text: T): T {
+        if (typeof text !== 'string') return text;
+        return text
+            .replace(/&lt;/g, '<')
+            .replace(/&gt;/g, '>')
+            .replace(/&quot;/g, '"')
+            .replace(/&#39;/g, "'")
+            .replace(/&amp;/g, '&') as T;
+    }
+    export function text(text:string){
+        return segment('text',{text});
+    }
+    export function face(id:string,text?:string){
+        return segment('face',{id,text});
+    }
+    export function from(content: SendContent): SendContent {
+        if (!Array.isArray(content)) content=[content];
+        const toString=(template:string|MessageSegment)=>{
+            if(typeof template!=='string') return [template]
+            template=unescape(template);
+            const result: MessageSegment[] = [];
+            const closingReg = /<(\S+)(\s[^>]+)?\/>/;
+            const twinningReg = /<(\S+)(\s[^>]+)?>([\s\S]*?)<\/\1>/;
+            while (template.length) {
+                const [_, type, attrStr = '', child = ''] = template.match(twinningReg) || template.match(closingReg) || [];
+                if (!type) break;
+                const isClosing = closingReg.test(template);
+                const matched = isClosing ? `<${type}${attrStr}/>` : `<${type}${attrStr}>${child}</${type}>`;
+                const index = template.indexOf(matched);
+                const prevText = template.slice(0, index);
+                if (prevText)
+                    result.push({
+                        type: 'text',
+                        data: {
+                            text: unescape(prevText),
+                        },
+                    });
+                template = template.slice(index + matched.length);
+                const attrArr = [...attrStr.matchAll(/\s([^=]+)(?=(?=="([^"]+)")|(?=='([^']+)'))/g)];
+                const data = Object.fromEntries(
+                    attrArr.map(([source, key, v1, v2]) => {
+                        const value = v1 || v2;
+                        try {
+                            return [key, JSON.parse(unescape(value))];
+                        } catch {
+                            return [key, unescape(value)];
+                        }
+                    }),
+                );
+                if (child) {
+                    data.message = toString(child).map(({ type, data }) => ({ type, ...data }));
+                }
+                result.push({
+                    type: type,
+                    data,
+                });
+            }
+            if (template.length) {
+                result.push({
+                    type: 'text',
+                    data: {
+                        text: unescape(template),
+                    },
+                });
+            }
+            return result;
+        }
+        return content.reduce((result,item)=>{
+            result.push(...toString(item))
+            return result;
+        },[] as MessageSegment[])
+    }
+    export function raw(content:SendContent){
+        if(!Array.isArray(content)) content=[content]
+        return content.map(item=>{
+            if(typeof item==='string') return item
+            const {type,data}=item
+            if(type==='text') return data.text
+            return data.text?`{${type}}(${data.text})`:`{${type}}`;
+        }).join('')
+    }
+    export function toString(content:SendContent){
+        if(!Array.isArray(content)) content=[content]
+        return content.map(item=>{
+            if(typeof item==='string') return item
+            const {type,data}=item
+            if(type==='text') return data.text
+            return `<${type} ${Object.keys(data).map(key=>`${key}='${escape(JSON.stringify(data[key]))}'`).join(' ')}/>`
+        }).join('')
+    }
+}
+
+export function remove<T>(list: T[], fn: (item: T) => boolean): void;
+export function remove<T>(list: T[], item: T): void;
+export function remove<T>(list: T[], arg: T | ((item: T) => boolean)) {
+    const index =
+        typeof arg === 'function' && !list.every(item => typeof item === 'function')
+            ? list.findIndex(arg as (item: T) => boolean)
+            : list.indexOf(arg as T);
+    if (index !== -1) list.splice(index, 1);
+}
+export function isEmpty<T>(item:T){
+    if(Array.isArray(item)) return item.length===0
+    if(typeof item==='object'){
+        if(!item) return true
+        return Reflect.ownKeys(item).length===0
+    }
+    return false
+}
+
+export namespace Time {
+    export const millisecond = 1;
+    export const second = 1000;
+    export const minute = second * 60;
+    export const hour = minute * 60;
+    export const day = hour * 24;
+    export const week = day * 7;
+
+    let timezoneOffset = new Date().getTimezoneOffset();
+
+    export function setTimezoneOffset(offset: number) {
+        timezoneOffset = offset;
+    }
+
+    export function getTimezoneOffset() {
+        return timezoneOffset;
+    }
+
+    export function getDateNumber(date: number | Date = new Date(), offset?: number) {
+        if (typeof date === 'number') date = new Date(date);
+        if (offset === undefined) offset = timezoneOffset;
+        return Math.floor((date.valueOf() / minute - offset) / 1440);
+    }
+
+    export function fromDateNumber(value: number, offset?: number) {
+        const date = new Date(value * day);
+        if (offset === undefined) offset = timezoneOffset;
+        return new Date(+date + offset * minute);
+    }
+
+    const numeric = /\d+(?:\.\d+)?/.source;
+    const timeRegExp = new RegExp(
+        `^${['w(?:eek(?:s)?)?', 'd(?:ay(?:s)?)?', 'h(?:our(?:s)?)?', 'm(?:in(?:ute)?(?:s)?)?', 's(?:ec(?:ond)?(?:s)?)?']
+            .map(unit => `(${numeric}${unit})?`)
+            .join('')}$`,
+    );
+
+    export function parseTime(source: string) {
+        const capture = timeRegExp.exec(source);
+        if (!capture) return 0;
+        return (
+            (parseFloat(capture[1]) * week || 0) +
+            (parseFloat(capture[2]) * day || 0) +
+            (parseFloat(capture[3]) * hour || 0) +
+            (parseFloat(capture[4]) * minute || 0) +
+            (parseFloat(capture[5]) * second || 0)
+        );
+    }
+
+    export function parseDate(date: string) {
+        const parsed = parseTime(date);
+        if (parsed) {
+            date = (Date.now() + parsed) as any;
+        } else if (/^\d{1,2}(:\d{1,2}){1,2}$/.test(date)) {
+            date = `${new Date().toLocaleDateString()}-${date}`;
+        } else if (/^\d{1,2}-\d{1,2}-\d{1,2}(:\d{1,2}){1,2}$/.test(date)) {
+            date = `${new Date().getFullYear()}-${date}`;
+        }
+        return date ? new Date(date) : new Date();
+    }
+
+    export function formatTimeShort(ms: number) {
+        const abs = Math.abs(ms);
+        if (abs >= day - hour / 2) {
+            return Math.round(ms / day) + 'd';
+        } else if (abs >= hour - minute / 2) {
+            return Math.round(ms / hour) + 'h';
+        } else if (abs >= minute - second / 2) {
+            return Math.round(ms / minute) + 'm';
+        } else if (abs >= second) {
+            return Math.round(ms / second) + 's';
+        }
+        return ms + 'ms';
+    }
+
+    export function formatTime(ms: number) {
+        let result: string;
+        if (ms >= day - hour / 2) {
+            ms += hour / 2;
+            result = Math.floor(ms / day) + ' 天';
+            if (ms % day > hour) {
+                result += ` ${Math.floor((ms % day) / hour)} 小时`;
+            }
+        } else if (ms >= hour - minute / 2) {
+            ms += minute / 2;
+            result = Math.floor(ms / hour) + ' 小时';
+            if (ms % hour > minute) {
+                result += ` ${Math.floor((ms % hour) / minute)} 分钟`;
+            }
+        } else if (ms >= minute - second / 2) {
+            ms += second / 2;
+            result = Math.floor(ms / minute) + ' 分钟';
+            if (ms % minute > second) {
+                result += ` ${Math.floor((ms % minute) / second)} 秒`;
+            }
+        } else {
+            result = Math.round(ms / second) + ' 秒';
+        }
+        return result;
+    }
+
+    const dayMap = ['日', '一', '二', '三', '四', '五', '六'];
+
+    function toDigits(source: number, length = 2) {
+        return source.toString().padStart(length, '0');
+    }
+
+    export function template(template: string, time = new Date()) {
+        return template
+            .replace('yyyy', time.getFullYear().toString())
+            .replace('yy', time.getFullYear().toString().slice(2))
+            .replace('MM', toDigits(time.getMonth() + 1))
+            .replace('dd', toDigits(time.getDate()))
+            .replace('hh', toDigits(time.getHours()))
+            .replace('mm', toDigits(time.getMinutes()))
+            .replace('ss', toDigits(time.getSeconds()))
+            .replace('SSS', toDigits(time.getMilliseconds(), 3));
+    }
+
+    function toHourMinute(time: Date) {
+        return `${toDigits(time.getHours())}:${toDigits(time.getMinutes())}`;
+    }
+
+    export function formatTimeInterval(time: Date, interval?: number) {
+        if (!interval) {
+            return template('yyyy-MM-dd hh:mm:ss', time);
+        } else if (interval === day) {
+            return `每天 ${toHourMinute(time)}`;
+        } else if (interval === week) {
+            return `每周${dayMap[time.getDay()]} ${toHourMinute(time)}`;
+        } else {
+            return `${template('yyyy-MM-dd hh:mm:ss', time)} 起每隔 ${formatTime(interval)}`;
+        }
+    }
+}
+export function sleep(ms: number) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/tests/adapter.test.ts

@@ -8,20 +8,27 @@ import type { BotConfig } from '../src/types'
 describe('适配器类测试', () => {
   // 创建测试用的Bot类
   class TestBot implements Bot {
-    connected = false
+    $connected = false
+    $config: BotConfig
 
-    constructor(public plugin: Plugin, public config: BotConfig) {}
+    constructor(public plugin: Plugin, config: BotConfig) {
+      this.$config = config
+    }
+
+    async $connect(): Promise<void> {
+      this.$connected = true
+    }
 
-    async connect(): Promise<void> {
-      this.connected = true
+    async $disconnect(): Promise<void> {
+      this.$connected = false
     }
 
-    async disconnect(): Promise<void> {
-      this.connected = false
+    async $sendMessage(): Promise<void> {
+      if (!this.$connected) throw new Error('机器人未连接')
     }
 
-    async sendMessage(): Promise<void> {
-      if (!this.connected) throw new Error('机器人未连接')
+    $formatMessage(message: any): any {
+      return message
     }
   }
 
@@ -68,8 +75,8 @@ describe('适配器类测试', () => {
       expect(adapter.bots.size).toBe(2)
       expect(adapter.bots.get('test-bot-1')).toBeDefined()
       expect(adapter.bots.get('test-bot-2')).toBeDefined()
-      expect(adapter.bots.get('test-bot-1')?.connected).toBe(true)
-      expect(adapter.bots.get('test-bot-2')?.connected).toBe(true)
+      expect(adapter.bots.get('test-bot-1')?.$connected).toBe(true)
+      expect(adapter.bots.get('test-bot-2')?.$connected).toBe(true)
 
       expect(loggerSpy).toHaveBeenCalledWith('bot test-bot-1 of adapter test-adapter connected')
       expect(loggerSpy).toHaveBeenCalledWith('bot test-bot-2 of adapter test-adapter connected')
@@ -106,7 +113,7 @@ describe('适配器类测试', () => {
   describe('错误处理测试', () => {
     it('应该处理机器人连接失败', async () => {
       class FailingBot extends TestBot {
-        async connect(): Promise<void> {
+        async $connect(): Promise<void> {
           throw new Error('连接失败')
         }
       }
@@ -123,7 +130,7 @@ describe('适配器类测试', () => {
 
     it('应该处理机器人断开连接失败', async () => {
       class FailingBot extends TestBot {
-        async disconnect(): Promise<void> {
+        async $disconnect(): Promise<void> {
           throw new Error('断开连接失败')
         }
       }
@@ -148,20 +155,27 @@ describe('适配器类测试', () => {
       }
 
       class ExtendedBot implements Bot<ExtendedBotConfig> {
-        connected = false
+        $connected = false
+        $config: ExtendedBotConfig
 
-        constructor(public plugin: Plugin, public config: ExtendedBotConfig) {}
+        constructor(public plugin: Plugin, config: ExtendedBotConfig) {
+          this.$config = config
+        }
+
+        async $connect(): Promise<void> {
+          this.$connected = true
+        }
 
-        async connect(): Promise<void> {
-          this.connected = true
+        async $disconnect(): Promise<void> {
+          this.$connected = false
         }
 
-        async disconnect(): Promise<void> {
-          this.connected = false
+        async $sendMessage(): Promise<void> {
+          if (!this.$connected) throw new Error('机器人未连接')
         }
 
-        async sendMessage(): Promise<void> {
-          if (!this.connected) throw new Error('机器人未连接')
+        $formatMessage(message: any): any {
+          return message
         }
       }
 
@@ -180,8 +194,8 @@ describe('适配器类测试', () => {
 
       const bot = extendedAdapter.bots.get('extended-bot')
       expect(bot).toBeDefined()
-      expect(bot?.config.token).toBe('test-token')
-      expect(bot?.config.platform).toBe('test-platform')
+      expect(bot?.$config.token).toBe('test-token')
+      expect(bot?.$config.platform).toBe('test-platform')
     })
   })
 })

package/tests/app.test.ts

@@ -137,6 +137,36 @@ describe('App类测试', () => {
     it('当上下文不存在时应该抛出错误', () => {
       expect(() => app.getContext('non-existent')).toThrow("can't find Context of non-existent")
     })
+
+    it('应该正确设置和获取上下文描述', async () => {
+      // 创建测试插件
+      const plugin = app.createDependency('test-plugin-desc', 'test-plugin-desc.ts')
+      
+      // 注册带描述的上下文  
+      const context = {
+        name: 'test-context',
+        description: '这是一个测试上下文，用于验证描述字段功能',
+        mounted: () => ({ testValue: 'test' }),
+        dispose: () => {}
+      }
+      plugin.register(context)
+      
+      // 等待插件挂载
+      await plugin.mounted()
+      
+      // 使用上下文来验证功能
+      plugin.useContext('test-context', () => {
+        // 验证上下文可以正常获取（先测试基本功能）
+        const retrievedContext = app.getContext('test-context')
+        expect(retrievedContext).toEqual({ testValue: 'test' })
+        
+        // 验证上下文列表包含描述信息
+        const contextList = app.contextList
+        const testContext = contextList.find(ctx => ctx.name === 'test-context')
+        expect(testContext).toBeDefined()
+        expect(testContext?.description).toBe('这是一个测试上下文，用于验证描述字段功能')
+      })
+    })
   })
 
   describe('消息处理测试', () => {