@lyrasoft/ts-toolkit
v0.2.3
Published
LYRASOFT Typescript utilities tools.
Downloads
110
Readme
LYRASOFT TS Utilities
LYRASOFT 專案用各類實用 TS/JS 工具集。
安裝
yarn add @lyrasoft/ts-toolkit --dev入口
主要有三個入口
// 一般專案用
import { ... } from '@lyrasoft/ts-toolkit/generic';
// Vite/Vue 專案用
import { ... } from '@lyrasoft/ts-toolkit/vue';
// Ionic/Vue 專案用
import { ... } from '@lyrasoft/ts-toolkit/ionic';主要差異在某些 UI 介面，Ionic 的版本會改用 Ionic 專屬 UI 元素。
其他入口因為個別有不同的相依，要獨立載入
// Datetime
import { ... } from '@lyrasoft/ts-toolkit/datetime';
// SweetAlert
import { ... } from '@lyrasoft/ts-toolkit/sweetalert';
// Vue Composable
import { ... } from '@lyrasoft/ts-toolkit/vue/composable';
// Vue Loading Overlay
import { ... } from '@lyrasoft/ts-toolkit/vue/loading-overlay';Generic
AlertAdapter
預設的 AlertAdapter 用內建 alert()，如果你想要在專案中改用 SweetAlert 可以先安裝
yarn add sweetalert --dev然後在 main.ts 設定
import { useSweetAlertAdapter } from '@lyrasoft/ts-toolkit/generic';
useSweetAlertAdapter(true);這樣就可以用以下函式快速呼叫 SweetAlert，有三個常用函式
import { simpleAlert, simpleConfirm, simpleDeleteConfirm } from '@lyrasoft/ts-toolkit/generic';
// Alert
await simpleAlert('Title', 'text', 'icon');
// 第四個參數可以覆蓋 swal options
await simpleAlert('Title', 'text', 'icon', { buttons: ['Cancel', 'OK'] });
// Confirm
const v = await simpleConfirm('Confirm title', 'Text', 'icon');
if (v) {
// ...
}
// Delete Confirm (顯示的文字會不一樣)
const d = await simpleDeleteConfirm('Confirm title', 'Text', 'icon');
if (d) {
// ...
}載入 Bootstrap 樣式
// 要放在 BS _variables.scss 後面，因為會用到 BS 變數
@import "@lyrasoft/ts-toolkit/scss/sweetalert-bootstrap5";
// ...手動覆蓋，如果你的專案用的是別套 alert，可以手動設定
import { AlertAdapter } from '@lyrasoft/ts-toolkit/generic';
AlertAdapter.alert = (title: string, text?: string, icon?: string, extra?: any) => Promise<boolean>;
AlertAdapter.confirm = (title: string, text?: string, icon?: string, extra?: any) => Promise<boolean>;
AlertAdapter.deleteConfirm = (title: string, text?: string, icon?: string, extra?: any) => Promise<boolean>;設定文字
import { AlertAdapter } from './alert-adapter';
AlertAdapter.confirmText = () => '確認';
AlertAdapter.cancelText = () => '取消';
AlertAdapter.deleteText = () => '刪除';Notify
AlertAdapter 也有 notify()，但預設是用 console.log()，讓你在自己的專案中，取代成其他的 notify or toast 套件，
要調用時，呼叫 simpleNotify()。
import { simpleNotify } from '@lyrasoft/ts-toolkit/generic';
const clear = await simpleNotify('text', 'text'); // type: info | warn | error
// Clear single message
clear();另外也能用 clearNotifities() 一次清除所有訊息
import { clearNotifities } from '@lyrasoft/ts-toolkit/generic';
await clearNotifities();如果你想要改用其他套件，可以手動覆蓋
import { AlertAdapter } from '@lyrasoft/ts-toolkit/generic';
AlertAdapter.notify = async (title: string, text?: string, type?: string) => {
const id = simeToastPackage.show(title, text, { type });
return () => {
simeToastPackage.clear(id);
};
};
AlertAdapter.clearNotifities = async () => {
simeToastPackage.clearAll();
};Crypto
import {
base64UrlDecode,
base64UrlEncode,
randomBytesString,
randomString,
STR_SEED_BASE62,
tid,
uid,
} from '@lyrasoft/ts-toolkit/generic';
uid();
tid();
randomBytesString(16);
randomString(32, STR_SEED_BASE62);
base64UrlEncode();
base64UrlDecode();DateTime
簡單的 dateToFormat() 用於任何地方。需要先安裝 dayjs
yarn add dayjs --dev
<script lang="ts" setup>
import { dateToFormat, DateFormat } from '@lyrasoft/ts-toolkit/datetime';
</script>
<template>
<div>
{{ dateToFormat(item.created, 'yyyy-MM-dd') }}
{{ dateToFormat(item.created, DateFormat.YMD_HI) }}
</div>
</template>Number
import { numberFormat } from '@lyrasoft/ts-toolkit/generic';
numberFormat(123456); // 123,456Queue & Stack
import { queue, stack } from './queue';
const q = queue(1); // 一次只能執行一個
// 會依序執行
q.push(async () => ...);
q.push(async () => ...);
q.push(async () => ...);
q.push(async () => ...);
// -------------
const s = stack();
s.observe(() => ...) // 監聽改變
s.push(...);
s.push(...);
s.push(...);
s.push(...);
s.pop(); // 觸發事件Promise
快速建立可以從外部 resolve 的 Promise
import { promiseWithResolvers } from '@lyrasoft/ts-toolkit/generic';
const { promise, resolve ,reject } = promiseWithResolvers();
resolve();等同 ES2024 Promise.withResolvers()
Timing
快速 sleep，用來取代 setTimeout()
import { sleep } from '@lyrasoft/ts-toolkit/generic';
await sleep(500);nextTick() 快速將後續程式推入下個循環
await nextTick();
nextTick().then(() => ...);
// OR
nextTick(() => ...);Typography
一些印出文字或摘要的方便函式
import { nl2br, htmlEscape, stripHtml, summaryText } from '@lyrasoft/ts-toolkit/generic';
// NL to <br>
nl2br(text);
// Escape HTML 後，再將 nl to <br>
// 用來印出換行的純文字
htmlEscape(text, true);
// 移除 HTML tags
stripHtml(html);
// 截斷文字，並且如果有截斷的話，顯示 ...
summaryText(text, 150);Vue 專用
需要安裝 vue
Reactive
unrefs() 用來將物件內的 refs 轉回一般變數，方便用在呼叫 API 時丟參數
import { unrefs } from '@lyrasoft/ts-toolkit/vue';
import { ref } from 'vue';
const foo = ref();
const bar = ref();
await apiClient.post(
'api/foo/item',
unrefs({
foo,
bar
})
)wrapRef() 與 wrapRefs() 則用來強制包裹變數成為 ref，若原本已是 ref 或 computed 則原封不動返回。
Loading
常用的 useLoading() 現在可以直接呼叫，不用自己寫了
<script lang="ts" setup>
import { useLoading } from '@lyrasoft/ts-toolkit/vue';
const { loading, run } = useLoading();
async function submit() {
await run(async () => {
const res = await apiClient.post(...);
// ...
});
}
</script>
<template>
<button :disabled="loading" @click="submit">Submit</button>
</template>LifeCycle
需要 vue-router
當 router 有時可能原地換頁時，我們通常會這樣寫：
import { onMounted } from 'vue';
import { onBeforeRouteUpdate, useRoute } from 'vue-router';
const route = useRoute();
onMounted(() => {
loadItem(route.params.id);
});
onBeforeRouteUpdate((to) => {
loadItem(to.params.id);
});現在我們可以這樣寫
import { onMountedOrRouteUpdate } from '@lyrasoft/ts-toolkit/vue/composable';
onMountedOrRouteUpdate((to) => {
loadItem(to.params.id);
});另外，如果搭配 Suspense 時，可能會這樣寫
import { onBeforeRouteUpdate, useRoute } from 'vue-router';
const route = useRoute();
onBeforeRouteUpdate((to) => {
loadItem(to.params.id);
});
await loadItem(route.params.id);現在可以改成這樣做
import { onCreatedOrRouteUpdate } from '@lyrasoft/ts-toolkit/vue/composable';
const item = ref();
await onCreatedOrRouteUpdate(async (to) => {
item.value = await loadItem(to.params.id);
});如果您想要避免前面宣告的變數可能是 undefined，可以改成這樣：
import { loadInstantAndRouteUpdate } from '@lyrasoft/ts-toolkit/vue/composable';
const { item, bar, yoo } = await loadInstantAndRouteUpdate(async () => {
const res = await apiClient.get(...);
return res.data.data as {
item: FooItem,
bar: Bar,
yoo: Yoo,
};
});如此這些 API 載入回來的變數都不會有 undefined type，因為他們都是等待載入完後才宣告的。
Utilities
uniqueItem() 與 uniqueItemList() 用來將列表物件自動加上 uid
import { uniqueItemList } from '@lyrasoft/ts-toolkit/vue';
const res = await axios.get(...);
const rawItems = res.data.data;
// 型別會自動加上 uid
const items = uniqueItemList(items);
// 可以自訂欄位
const items = uniqueItemList(items, '__key');Ionic 專用
Alert
初始化
// main.ts
import { useIonicAlertAdapter } from '@lyrasoft/ts-toolkit/ionic';
useIonicAlertAdapter();這樣以下三個常用函式，就會自動轉成 Ionic 格式
simpleAlert();
simpleConfirm();
simpleDeleteConfirm();Loading
Ionic 額外多了 useLoadingOverlay() 可以用，可建立覆蓋全頁的 loading overlay
const { run, loading } = useLoadingOverlay('Loading...', options);常用工具組
import { ionicActionSheetConfirm, ionicToast } from '@lyrasoft/ts-toolkit/ionic';
ionicActionSheetConfirm('text', buttons);
ionicToast('text', position, 5000);後續
由於這是一個實用工具集，新功能會隨時加上去。如果文件沒看到，可以直接到原始碼裡面翻翻看有沒有用的上的東西。
如果你覺得缺少一個常用工具，可以直接開 PR 加上去。