amateras 0.10.0 → 0.10.2

package/packages/for/src/structure/For.ts

@@ -0,0 +1,74 @@
+import { onclient } from "@amateras/core";
+import { symbol_Statement } from "@amateras/core";
+import { Proto } from "@amateras/core";
+import { ProxyProto } from "@amateras/core";
+import type { Signal } from "@amateras/signal";
+import { forEach } from "@amateras/utils";
+
+export type ForLayout<T> = (item: T, index: number) => void;
+export type ForList<T extends object = object> = Signal<T[]> | Signal<Set<T>>
+
+export class For<T extends object = object> extends ProxyProto {
+    static override [symbol_Statement] = true;
+    #layout: ForLayout<T>;
+    list$: ForList<T>;
+    #itemProtoMap = new WeakMap<T, ForItem>();
+    declare protos: Set<ForItem>;
+    constructor(list: ForList<T>, layout: ForLayout<T>) {
+        super();
+        this.list$ = list;
+        this.#layout = layout;
+
+        let update = () => {
+            let {n: newItemList, d: deleteItemList} = this.run();
+            forEach(newItemList, proto => proto.build());
+            // 如果 For node 没有 parentNode，代表 For 并不在 DOM 树中
+            // 跳过处理 DOM 的步骤
+            if (!this.node?.parentNode) return;
+            forEach(deleteItemList, proto => proto.removeNode());
+            let nodes = onclient() ? this.toDOM() : [];
+            let prevNode: Node | undefined
+            forEach(nodes, node => {
+                if (node.parentNode) prevNode = node;
+                else prevNode = prevNode?.parentNode?.insertBefore(node, prevNode.nextSibling)
+            })
+        }
+
+        this.list$.subscribe(update);
+        this.disposers.add(() => this.list$.unsubscribe(update));
+    }
+
+    override build() {
+        this.#itemProtoMap = new WeakMap();
+        this.run();
+        forEach(this.protos, itemProto => itemProto.build());
+        return this;
+    }
+
+    run() {
+        let newItemList: ForItem[] = [];
+        let oldItemList = new Set(this.protos);
+        this.clear();
+        forEach(this.list$.value, (item, i) => {
+            let itemProto = this.#itemProtoMap.get(item);
+            if (!itemProto) {
+                itemProto = new ForItem();
+                newItemList.push(itemProto);
+                this.#itemProtoMap.set(item, itemProto);
+                itemProto.layout = () => this.#layout(item, i);
+            }
+            else oldItemList.delete(itemProto);
+            itemProto.parent = this;
+        })
+        return { n: newItemList, d: oldItemList }
+    }
+
+    override removeNode(): void {
+        this.node?.remove();
+        forEach(this.protos, proto => proto.removeNode())
+    }
+}
+
+export class ForItem extends Proto {
+    static override [symbol_Statement] = true
+}

package/packages/hmr/package.json

@@ -0,0 +1,13 @@
+{
+    "name": "@amateras/hmr",
+    "type":"module",
+    "peerDependencies": {
+    },
+    "imports": {
+      "#structure/*": "./src/structure/*.ts",
+      "#lib/*": "./src/lib/*.ts"
+    },
+    "exports": {
+      ".": "./src/index.ts"
+    }
+}

package/packages/hmr/src/index.ts

@@ -0,0 +1,27 @@
+export const viteHMR = {
+    name: 'auto-hmr-accept',
+    apply: 'serve',
+    handleHotUpdate({file, server}: {file: string, server: any}) {
+        if (file.includes('amateras/packages/')) {
+            console.log(`package file changes, force reload: ${file}`)
+            server.ws.send({
+                type: 'full-reload',
+                path: '*'
+            })
+            return []
+        }
+    },
+    transform(content: string, pathname: string) {
+        if (pathname.includes('node_modules') || !/\.(js|ts)$/.test(pathname)) return;
+        if (pathname.includes('amateras/packages/')) return {
+            code: `${content}\nif (import.meta.hot) import.meta.hot.decline();`,
+            map: null
+        }
+        if (!content.includes('import.meta.hot.accept')) return {
+            code: `${content}\nif (import.meta.hot) import.meta.hot.accept();`,
+            map: null 
+        };
+    }
+} as const
+
+export default viteHMR;

package/packages/i18n/README.md

@@ -0,0 +1,73 @@
+# amateras/i18n
+
+## Usage
+```ts
+import 'amateras';
+import 'amateras/i18n';
+
+const $t = $.i18n()
+// add 'en' locale dictionary context
+.add('en', {
+    homepage: {
+        _: 'Home',
+        hello: 'Hello, $name$!',
+    }
+})
+// set 'en' as locale language
+.locale('en')
+
+$(document.body).content([
+    $('h1').content( $t('homepage') )
+    // <h1><text>Home</text></h1>
+    $t('homepage.hello', {name: 'Amateras'}) 
+    // <text>Hello, Amateras!</text>
+])
+```
+
+## Change Language
+```ts
+$t.locale('zh')
+// all translation text will be updated
+```
+
+## Import Dictionary Context
+
+```ts
+// ./i18n/en.ts
+export default {
+    hello: 'Hello, $name$!'
+}
+
+// ./i18n/zh.ts
+export default {
+    hello: '您好，$name$！'
+}
+
+// ./entry_file.ts
+const $t = $.i18n()
+.add('en', () => import('./i18n/en.ts'))
+.add('zh', () => import('./i18n/zh.ts'))
+// set 'zh' as locale language
+// and fetch file automatically from path
+.locale('zh');
+```
+
+## Directory Shortcut
+
+```ts
+const $t = $.i18n('en')
+.add('en', {
+    page1: {
+        section2: {
+            button3: {
+                text: 'Too deep!'
+            }
+        }
+    }
+})
+
+const $t_button = $t.dir('page1.section2.button3');
+
+$t_button('text') // Too deep!
+$t('page1.section2.button3.text') // Too deep!
+```

package/packages/i18n/package.json

@@ -0,0 +1,15 @@
+{
+    "name": "@amateras/i18n",
+    "peerDependencies": {
+      "@amateras/core": "workspace:*",
+      "@amateras/utils": "workspace:*"
+    },
+    "imports": {
+      "#structure/*": "./src/structure/*.ts",
+      "#lib/*": "./src/lib/*.ts",
+      "#node/*": "./src/node/*.ts"
+    },
+    "exports": {
+      ".": "./src/index.ts"
+    }
+}

package/packages/i18n/src/index.ts

@@ -0,0 +1,78 @@
+import { I18n } from "#structure/I18n";
+import { I18nDictionary, type I18nDictionaryContext, type I18nDictionaryContextImporter } from "#structure/I18nDictionary";
+import { I18nTranslation as _I18nTranslation, I18nTranslation, type I18nTranslationOptions } from "#structure/I18nTranslation";
+import { _instanceof, _Object_assign } from "@amateras/utils";
+import type { GetDictionaryContextByKey, I18nTranslationDirKey, I18nTranslationKey, I18nTranslationParams, Mixin, ResolvedAsyncDictionary } from "./types";
+import { GlobalState } from "@amateras/core";
+
+declare global {
+    export namespace $ {
+        export interface I18nFunction<D extends I18nDictionaryContext = {}> {
+            <K extends I18nTranslationKey<D>, P extends I18nTranslationParams<K, D>>(path: K, ...params: P extends Record<string, never> ? [] : [P]): I18nTranslation;
+            i18n: I18n;
+            locale(lang?: string): Promise<void>;
+            add<F extends I18nDictionaryContext | I18nDictionaryContextImporter>(lang: string, dictionary: F): I18nFunction<Mixin<D, (F extends I18nDictionaryContextImporter ? ResolvedAsyncDictionary<F> : F)>>;
+            delete(lang: string): this;
+            dir<K extends I18nTranslationDirKey<D>>(path: K): I18nFunction<GetDictionaryContextByKey<K, D>>
+        }
+        export function i18n(defaultLocale: string): I18nFunction;
+        export type I18nTranslation = _I18nTranslation;
+
+        export interface TextProcessorValueMap {
+            i18n: I18nTranslation
+        }
+    }
+}
+
+declare module '@amateras/core' {
+    export interface GlobalState {
+        i18n: {
+            promises: Promise<any>[]
+        }
+    }
+}
+
+_Object_assign(GlobalState.prototype, {
+    i18n: {
+        promises: []
+    }
+})
+
+GlobalState.disposers.add(global => {
+    global.i18n.promises = [];
+})
+
+_Object_assign($, {
+    i18n(defaultLocale: string) {
+        const i18n = new I18n(defaultLocale);
+        const i18nFn = (key: string, options?: I18nTranslationOptions) => i18n.translate(key, options);
+        _Object_assign(i18nFn, { 
+            i18n,
+            async locale(locale: string) {
+                await i18n.setLocale(locale);
+            },
+            add(lang: string, context: I18nDictionaryContext | I18nDictionaryContextImporter) {
+                i18n.map.set(lang, new I18nDictionary(context));
+                return this;
+            },
+            delete(lang: string) {
+                i18n.map.delete(lang);
+                return this;
+            },
+            dir(path: string) {
+                return (key: string, options?: I18nTranslationOptions) => i18n.translate(`${path}.${key}`, options)
+            }
+        })
+        return i18nFn
+    }
+})
+
+$.process.text.add(value => {
+    if (_instanceof(value, I18nTranslation)) {
+        return value
+    }
+})
+
+export * from "#structure/I18n";
+export * from "#structure/I18nDictionary";
+export * from "#structure/I18nTranslation";

package/packages/i18n/src/structure/I18n.ts

@@ -0,0 +1,51 @@
+import { _instanceof, _null, map } from "@amateras/utils";
+import { I18nDictionary } from "#structure/I18nDictionary";
+import { I18nTranslation, type I18nTranslationOptions } from "./I18nTranslation";
+
+export class I18n {
+    map = new Map<string, I18nDictionary>();
+    #defaultLocale: string;
+    translations = new Set<I18nTranslation>();
+    locale: string;
+    constructor(defaultLocale: string) {
+        this.#defaultLocale = defaultLocale;
+        this.locale = defaultLocale;
+    }
+
+    defaultLocale(): string;
+    defaultLocale(locale: string): this;
+    defaultLocale(locale?: string) {
+        if (!arguments.length) return this.#defaultLocale;
+        if (locale) this.#defaultLocale = locale;
+        return this;
+    }
+
+    async setLocale(): Promise<string>;
+    async setLocale(locale: string): Promise<this>;
+    async setLocale(locale?: string) {
+        if (!arguments.length) return this.locale;
+        if (locale) {
+            let dictionary = this.map.get(locale);
+            if (!dictionary) {
+                locale = locale.split('-')[0]!;
+                return this.setLocale(locale);
+            }
+            if (locale !== this.locale) {
+                this.locale = locale;
+                await Promise.all(map(this.translations, translation => translation.update()))
+            }
+        }
+        return this;
+    }
+
+    dictionary(locale = this.locale) {
+        if (!locale) return _null;
+        const dictionary = this.map.get(locale);
+        return dictionary;
+    }
+
+    translate(key: string, options?: I18nTranslationOptions) {
+        return new I18nTranslation(this, key, options);
+    }
+}
+

package/packages/i18n/src/structure/I18nDictionary.ts

@@ -0,0 +1,31 @@
+import { _instanceof, isFunction, isObject } from "@amateras/utils";
+
+export class I18nDictionary {
+    #context: I18nDictionaryContext | Promise<I18nDictionaryContext> | null = null;
+    #fetch: I18nDictionaryContextImporter | null = null;
+    constructor(resolver: I18nDictionaryContext | I18nDictionaryContextImporter) {
+        if (isFunction(resolver)) this.#fetch = resolver;
+        else this.#context = resolver;
+    }
+
+    async context(): Promise<I18nDictionaryContext> {
+        if (this.#context) return await this.#context;
+        if (!this.#fetch) throw 'I18n Context Fetch Error';
+        return this.#context = this.#fetch().then((module) => module.default);
+    }
+
+    async find(path: string, context?: I18nDictionaryContext): Promise<string | undefined> {
+        if (!context) context = await this.context();
+        const [snippet, ...rest] = path.split('.') as [string, ...string[]];
+        const target = context[snippet];
+        if (isObject(target)) {
+            if (rest.length) return this.find(rest.join('.'), target);
+            else return target['_'] as string;
+        } 
+        if (rest.length) return path;
+        else return target;
+    }
+}
+
+export type I18nDictionaryContext = {[key: string]: string | I18nDictionaryContext}
+export type I18nDictionaryContextImporter = () => Promise<{default: I18nDictionaryContext}>

package/packages/i18n/src/structure/I18nTranslation.ts

@@ -0,0 +1,51 @@
+import type { I18n } from "#structure/I18n";
+import { ProxyProto } from "@amateras/core";
+import { forEach, isUndefined, map } from "@amateras/utils";
+
+export class I18nTranslation extends ProxyProto {
+    i18n: I18n;
+    key: string;
+    options: I18nTranslationOptions | undefined;
+    constructor(i18n: I18n, key: string, options?: I18nTranslationOptions) {
+        super()
+        this.i18n = i18n;
+        this.key = key;
+        this.options = options;
+        this.i18n.translations.add(this);
+    }
+    
+    override build(): this {
+        this.update();
+        return this;
+    }
+    
+    async update() {
+        const {key, i18n, options} = this;
+        const contentUpdate = (content: string[], args: any[] = []) => {
+            this.layout = () => {
+                // make this array become Template String Array;
+                //@ts-ignore
+                content.raw = content;
+                $(content as any, ...args);
+            }
+            forEach(this.protos, proto => proto.removeNode());
+            super.build();
+            this.node?.replaceWith(...this.toDOM());
+        }
+        update: {
+            const dictionary = i18n.dictionary();
+            if (!dictionary) { contentUpdate([key]); break update }
+            const request = dictionary.find(key);
+            this.global.i18n.promises.push(request);
+            const translate = await request;
+            if (isUndefined(translate)) break update;
+            const snippets = translate.split(/\$[a-zA-Z0-9_]+\$/);
+            if (snippets.length === 1 || !options) { contentUpdate([translate]); break update }
+            const matches = translate.matchAll(/(\$([a-zA-Z0-9_]+)\$)/g);
+            contentUpdate(snippets, map(matches as unknown as [string, string, string][], ([,,value]) => options[value]));
+        }
+        return this;
+    }
+}
+
+export type I18nTranslationOptions = {[key: string]: any}

package/packages/i18n/src/types.ts

@@ -0,0 +1,77 @@
+import type { I18nDictionaryContext, I18nDictionaryContextImporter } from "#structure/I18nDictionary";
+
+export type ResolvedAsyncDictionary<F extends I18nDictionaryContextImporter> = Awaited<ReturnType<F>>['default'];
+
+export type I18nTranslationKey<T> = 
+    T extends I18nDictionaryContext
+    ?   {
+            [K in keyof T]: K extends string
+            ?   K extends '_' 
+                ?   never 
+                :   T[K] extends string
+                    ?   `${K}`
+                    :   '_' extends keyof T[K]
+                        ?   `${K}` | `${K}.${I18nTranslationKey<T[K]>}`
+                        :   `${K}.${I18nTranslationKey<T[K]>}`
+            :   never;
+        }[keyof T]
+    :   never;
+
+export type I18nTranslationDirKey<T> = 
+    T extends I18nDictionaryContext
+    ?   {
+            [K in keyof T]: K extends string
+            ?   T[K] extends string 
+                ?   never
+                :   `${K}` | `${K}.${I18nTranslationDirKey<T[K]>}`
+            :   never;
+        }[keyof T]
+    :   never;
+
+export type I18nTranslationParams<K extends string, T extends I18nDictionaryContext> = 
+    FindTranslationByKey<K, T> extends infer O
+    ?   O extends string
+        ?   FindParam<O>
+        :   never
+    :   never
+
+export type FindParam<T extends string> = 
+    T extends `${string}$${infer Param}$${infer Rest}`
+    ?   Param extends `${string}${' '}${string}`
+        ?   Prettify<{} & FindParam<Rest>>
+        :   Prettify<Record<Param, $.Layout> & FindParam<Rest>>
+    :   {}
+
+export type FindTranslationByKey<K extends string, T extends I18nDictionaryContext> = 
+    K extends `${infer Prefix}.${infer Rest}`
+    ?   Prefix extends keyof T
+        ?   T[Prefix] extends I18nDictionaryContext
+            ?   FindTranslationByKey<Rest, T[Prefix]>
+            :   T[Prefix]
+        :   ''
+    :   T[K] extends object
+        ?   '_' extends keyof T[K]
+            ?   T[K]['_']
+            :   never
+        :   T[K]
+
+export type GetDictionaryContextByKey<K extends string, T extends I18nDictionaryContext> =
+    K extends `${infer Prefix}.${infer Rest}`
+    ?   Prefix extends keyof T
+        ?   T[Prefix] extends I18nDictionaryContext
+            ?   GetDictionaryContextByKey<Rest, T[Prefix]>
+            :   never
+        :   never
+    :   T[K] extends object
+        ?   T[K]
+        :   never
+
+export type Mixin<A, B> = 
+    (Omit<A, keyof B> & Omit<B, keyof A>) & {
+        [key in (keyof A & keyof B)]: 
+            A[key] extends object
+            ?   B[key] extends object
+                ?   Mixin<A[key], B[key]>
+                :   A[key] | B[key]
+            :   A[key] | B[key]  
+    }

package/packages/idb/README.md

@@ -0,0 +1,127 @@
+# amateras/idb
+
+## Usage
+```ts
+import 'amateras';
+import 'amateras/idb';
+
+// configure indexedDB
+const idb = await $.idb('MyDB', 1)
+// add store
+.store('userStore', store => store
+    .keyPath('id')
+    .autoIncrement(true)
+    // define store object type
+    .schema<{
+        id: number,
+        name: string,
+        age: number
+    }>()
+    .index('by_age', { keyPath: 'age' })
+)
+// open idb
+.open();
+
+// open `readwrite` transaction with `userStore`
+const result = await idb.store('userStore', true, async store => {
+    store.put({name: 'Amateras', age: 16});
+    return store.getAll();
+})
+
+console.log(result); // [ { name: 'Amateras', age: 16, id: 1 } ]
+```
+
+## Quick Examples
+
+### Get object from store
+```ts
+await idb.store('userStore', store => store.get(1))
+```
+
+### Get all object from store
+```ts
+await idb.store('userStore', store => store.getAll())
+```
+
+### Add object to store
+Any changes to database without `readwrite` mode is resisted, pass `true` value to `writable` argument to enable `readwrite` mode.
+``` ts
+await idb.store('userStore', true, store => store.add({name: 'Tsukimi', age: 16}))
+```
+
+### Put object to store
+The `.put()` method is different with `.add()` method, put object will replace the object of existed key.
+``` ts
+await idb.store('userStore', true, store => store.put({name: 'Amateras', age: 17}))
+```
+
+### Use index
+```ts
+await idb.store('userStore', true, store => store.index('by_age').getAll(16))
+```
+
+### Operating multiple stores in one transaction
+```ts
+await idb.transaction(['userStore', 'itemStore'], true, async transaction => {
+    transaction.store('itemStore').put({id: 2, name: 'Item 2'})
+    return {
+        users: await transaction.store('userStore').getAll(),
+        items: await transaction.store('itemStore').getAll()
+    }
+})
+```
+
+### Open cursor for advance operations
+```ts
+await idb.store('userStore', true, async store => {
+    const teenagers = []
+    await store.cursor(cursor => {
+        if (cursor.value.age < 18) teenagers.push(cursor.value);
+        cursor.continue();
+    })
+    return teenagers;
+})
+```
+
+## Upgrade Database
+Using `.upgrade()` in `$IDBStoreBuilder` can set the store upgrade handle function to list. The store upgrade function is used for change object structure when the store is upgrading. 
+
+For example, in version 10:
+```ts
+{
+    id: number,
+    name: string
+}
+```
+
+After version 11, we want to change the object structure:
+```ts
+{
+    id: string,
+    name: string,
+    intro: string
+}
+```
+
+You see the `id` is change to `string` type, and come with the new property `intro`. In the following example, we will upgrade this object structure, and this upgrade is only executed when client IDB version is lower than argument `version`.
+
+```ts
+store.upgrade(11, (objects) => {
+    return objects.map({key, value} => {
+        // since we didn't defined the object type in every different version,
+        // the object is any type, please handle the upgrade carefully
+        return { key,
+            value: {
+                ...value,
+                id: value.id.toString(), // convert to string
+                intro: `Hi, my name is ${object.name}` // add new intro property
+            }
+        }
+    })
+})
+```
+
+The upgrade function is set, this will be executed on `$IDBBuilder.open()`.
+
+> [!NOTE]
+> You should leave all the upgrade function in your codebase, unless you are sure the client database version is larger than this upgrade function.

package/packages/idb/package.json

@@ -0,0 +1,16 @@
+{
+    "name": "@amateras/idb",
+    "peerDependencies": {
+      "@amateras/core": "workspace:*",
+      "@amateras/signal": "workspace:*",
+      "@amateras/utils": "workspace:*"
+    },
+    "imports": {
+      "#structure/*": "./src/structure/*.ts",
+      "#lib/*": "./src/lib/*.ts",
+      "#node/*": "./src/node/*.ts"
+    },
+    "exports": {
+      ".": "./src/index.ts"
+    }
+}

package/packages/idb/src/core.ts

@@ -0,0 +1,6 @@
+export * from '#structure/$IDB';
+export * from '#structure/$IDBTransaction';
+export * from '#structure/$IDBStoreBase';
+export * from '#structure/$IDBStore';
+export * from '#structure/$IDBIndex';
+export * from '#structure/$IDBCursor';

package/packages/idb/src/index.ts

@@ -0,0 +1,17 @@
+import { _Object_assign } from "@amateras/utils"
+import { $IDBBuilder } from "#structure/builder/$IDBBuilder"
+
+declare global {
+    export namespace $ {
+        /**
+         * Create {@link $IDBBuilder} with IDB name and version number.
+         * @param name - Database name
+         * @param version - Version number
+         */
+        export function idb<N extends string, V extends number>(name: N, version: V): $IDBBuilder<{name: N, version: V, stores: {}}>;
+    }
+}
+
+_Object_assign($, {
+    idb: (name: string, version: number) => new $IDBBuilder({name, version, stores: {}})
+})

package/packages/idb/src/lib/$IDBRequest.ts

@@ -0,0 +1,8 @@
+import { _Promise } from "@amateras/utils";
+
+export const $IDBRequest = <T>(req: IDBRequest<T>, handle?: (req: IDBRequest<T>, resolve: (value: T) => void) => void) => {
+    return new _Promise<T>((resolve, reject) => {
+        req.onsuccess = _ => handle ? handle(req, resolve) : resolve(req.result);
+        req.onerror = _ => reject(req.error);
+    })
+}