@lyrasoft/ts-toolkit

LYRASOFT TS Utilities

LYRASOFT 專案用各類實用 TS/JS 工具集。

• LYRASOFT TS Utilities
  • 安裝
    • 入口
  • Generic
    • AlertAdapter
    • Crypto
    • DateTime
    • Number
    • Queue & Stack
    • Promise
    • Timing
    • Typography
  • Vue 專用
    • Reactive
    • Loading
    • LifeCycle
    • Utilities
  • Ionic 專用
    • Alert
    • Loading
    • 常用工具組
  • 後續

安裝

yarn add @lyrasoft/ts-toolkit --dev

入口

主要有三個入口

// 一般專案用
import { ... } from '@lyrasoft/ts-toolkit/src/generic';

// Vite/Vue 專案用
import { ... } from '@lyrasoft/ts-toolkit/src/vue';

// Ionic/Vue 專案用
import { ... } from '@lyrasoft/ts-toolkit/src/ionic';

主要差異在某些 UI 介面，Ionic 的版本會改用 Ionic 專屬 UI 元素。

其他入口因為個別有不同的相依，要獨立載入

// SweetAlert
import { ... } from '@lyrasoft/ts-toolkit/src/sweetalert';

// Vue Composable
import { ... } from '@lyrasoft/ts-toolkit/src/vue/composable';

// Vue Loading Overlay
import { ... } from '@lyrasoft/ts-toolkit/src/vue/loading-overlay';

Generic

AlertAdapter

預設的 AlertAdapter 用內建 alert()，如果你想要在專案中改用 SweetAlert 可以先安裝

yarn add sweetalert --dev

然後在 main.ts 設定

import { useSweetAlertAdapter } from '@lyrasoft/ts-toolkit/src/generic';

useSweetAlertAdapter(true);

這樣就可以用以下函式快速呼叫 SweetAlert，有三個常用函式

import { simpleAlert, simpleConfirm, simpleDeleteConfirm } from '@lyrasoft/ts-toolkit/src/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/src/scss/sweetalert-bootstrap5";

// ...

手動覆蓋，如果你的專案用的是別套 alert，可以手動設定

import { AlertAdapter } from '@lyrasoft/ts-toolkit/src/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 = () => '刪除';

Crypto

import {
  base64UrlDecode,
  base64UrlEncode,
  randomBytesString,
  randomString, 
  STR_SEED_BASE62,
  tid,
  uid,
} from '@lyrasoft/ts-toolkit/src/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/src/generic';
</script>

<template>
  <div>
    {{ dateToFormat(item.created, 'yyyy-MM-dd') }}

    {{ dateToFormat(item.created, DateFormat.YMD_HI) }}
  </div>
</template>

Number

import { numberFormat } from '@lyrasoft/ts-toolkit/src/generic';

numberFormat(123456); // 123,456

Queue & 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/src/generic';

const { promise, resolve ,reject } = promiseWithResolvers();

resolve();

等同 ES2024 Promise.withResolvers()

Timing

快速 sleep，用來取代 setTimeout()

import { sleep } from '@lyrasoft/ts-toolkit/src/generic';

await sleep(500);

nextTick() 快速將後續程式推入下個循環

await nextTick();
nextTick().then(() => ...);

// OR

nextTick(() => ...);

Typography

一些印出文字或摘要的方便函式

import { nl2br, htmlEscape, stripHtml, summaryText } from '@lyrasoft/ts-toolkit/src/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/src/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/src/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/src/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/src/vue/composable';

const item = ref();

await onCreatedOrRouteUpdate(async (to) => {
  item.value = await loadItem(to.params.id);
});

如果您想要避免前面宣告的變數可能是 undefined，可以改成這樣：

import { loadInstantAndRouteUpdate } from '@lyrasoft/ts-toolkit/src/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/src/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/src/ionic';

useIonicAlertAdapter();

這樣以下三個常用函式，就會自動轉成 Ionic 格式

simpleAlert();
simpleConfirm();
simpleDeleteConfirm();

Loading

Ionic 額外多了 useLoadingOverlay() 可以用，可建立覆蓋全頁的 loading overlay

const { run, loading } = useLoadingOverlay('Loading...', options);

常用工具組

import { ionicActionSheetConfirm, ionicToast } from '@lyrasoft/ts-toolkit/src/ionic';

ionicActionSheetConfirm('text', buttons);
ionicToast('text', position, 5000);

後續

由於這是一個實用工具集，新功能會隨時加上去。如果文件沒看到，可以直接到原始碼裡面翻翻看有沒有用的上的東西。

如果你覺得缺少一個常用工具，可以直接開 PR 加上去。