jg-util

📦 安裝

npm install jg-util

🚀 使用方式

ES Module 匯入

import { 
  base64, 
  crypto, 
  files, 
  imageHandler,
  request,
  sleep,
  uuid 
} from 'jg-util'

個別匯入

import crypto from 'jg-util/src/crypto.mjs'
import files from 'jg-util/src/files.mjs'

📚 API 文件

base64 - Base64 編解碼

提供 Base64 編碼與解碼功能。

import { base64 } from 'jg-util'

// 編碼
base64.encode('Hello World')  // 'SGVsbG8gV29ybGQ='
base64.btoa('Hello World')    // 同上

// 解碼
base64.decode('SGVsbG8gV29ybGQ=')  // 'Hello World'
base64.atob('SGVsbG8gV29ybGQ=')    // 同上

clearJSON - JSON 清洗

從雜亂的文字內容中提取乾淨的 JSON 物件或陣列，特別適合處理 AI 回應中包含的 JSON。

import { clearJSON } from 'jg-util'

const messyText = `
這是一些說明文字
\`\`\`json
{"name": "test", "value": 123}
\`\`\`
還有一些結尾的文字
`

clearJSON(messyText)  // { name: 'test', value: 123 }

cookies - Cookie 管理

瀏覽器端 Cookie 操作工具。

import { cookies } from 'jg-util'

// 設定 Cookie
cookies.set('token', 'abc123')
cookies.set('token', 'abc123', { days: 30, domain: '.example.com', SameSite: 'Strict' })

// 取得 Cookie
cookies.get('token')  // 'abc123'
cookies.get()         // 取得所有 Cookie 物件

// 刪除 Cookie
cookies.del('token')

crypto - 加解密工具

提供 MD5、SHA、AES 等加密演算法。

import { crypto } from 'jg-util'

// MD5 雜湊
crypto.MD5('password')  // '5f4dcc3b5aa765d61d8327deb882cf99'

// SHA 雜湊
crypto.SHA.Encrypt('text')            // SHA-512 (預設)
crypto.SHA.Encrypt('text', 'sha256')  // SHA-256

// AES 加解密
const encrypted = crypto.AES.Encrypt('secret message', 'my-key')
const decrypted = crypto.AES.Decrypt(encrypted, 'my-key')  // 'secret message'

files - 檔案操作

完整的檔案系統操作工具（Node.js 環境）。

import { files } from 'jg-util'

// 取得目錄中的檔案
files.getFromDir({ 
  path: './images', 
  filter: ['.jpg', '.png'],  // 篩選副檔名
  all: true                   // 遞迴子目錄
})

// 讀取檔案內容
const result = await files.getContent('./data.json')
// { status: true, result: { text: '...', name: 'data', ext: '.json', ... } }

// 寫入檔案
files.exportData('./output.txt', 'Hello World')

// 檔案操作
await files.copy({ src: './a.txt', dest: './b.txt' })
await files.move({ src: './a.txt', dest: './c.txt' })
await files.remove({ src: './temp.txt' })

// 檢查檔案是否存在
const exists = await files.exist('./file.txt')  // true / false

// 取得檔案狀態
const stats = await files.getStats('./file.txt')

// 儲存 Buffer
await files.saveFile(buffer, './output.bin')

imageHandler - 圖片處理

基於 Sharp 的高效能圖片處理，額外支援 BMP 格式。

import { imageHandler } from 'jg-util'

// 調整圖片大小
const result = await imageHandler('./input.jpg', {
  width: 800,
  height: 600,
  fit: 'cover',        // 'cover' | 'contain' | 'fill' | 'inside' | 'outside'
  position: 'center',  // 裁切位置
  kernel: 'lanczos3'   // 縮放演算法
})

// 裁切圖片
const result = await imageHandler('./input.jpg', {
  extract: '100,100,400,300'  // left, top, width, height
})

// 處理透明背景
const result = await imageHandler('./input.bmp', {
  transparent: '255,255,255'  // 將白色轉為透明
})

// 回傳結果
// {
//   status: true,
//   result: {
//     image: Buffer,
//     mime: 'image/jpeg',
//     ext: '.jpeg'
//   }
// }

random - 隨機數生成

產生指定範圍內的隨機整數。

import { random } from 'jg-util'

random(1, 100)  // 1 ~ 100 之間的隨機整數
random(0, 9)    // 0 ~ 9 之間的隨機整數

request - HTTP 請求

具備超時處理機制的 fetch 封裝。

import { request } from 'jg-util'

// 基本請求
const response = await request('https://api.example.com/data')

// 帶選項的請求
const response = await request('https://api.example.com/data', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'test' })
}, 60000)  // 60 秒超時

// 超時會返回 504 狀態的 Response 物件

salt - 密碼加鹽

使用 SHA-512 進行密碼加鹽處理。

import { salt } from 'jg-util'

const hashedPassword = salt('myPassword', 'randomSaltString')

scrollTo - 平滑捲動

瀏覽器端平滑捲動到指定元素。

import { scrollTo } from 'jg-util'

// 捲動到指定元素
scrollTo('#target-section')
scrollTo(document.querySelector('.my-element'))

// 在指定容器內捲動
scrollTo('#target', '#scroll-container')

sleep - 延遲執行

Promise-based 的延遲函式。

import { sleep } from 'jg-util'

await sleep(1000)  // 等待 1 秒
console.log('1 秒後執行')

urlParams - URL 參數操作

瀏覽器端 URL 查詢參數操作工具。

import { urlParams } from 'jg-util'

// 取得參數
urlParams.get('id')    // 取得 ?id=xxx 的值
urlParams.get()        // 取得所有參數物件

// 設定參數（更新 URL）
urlParams.set({ page: 2, sort: 'desc' })
urlParams.set({ page: 3 }, true)  // 推送新歷史記錄
urlParams.set({ page: 3 }, true, '頁面標題')

uuid - UUID 生成

生成 UUID v4。

import { uuid } from 'jg-util'

uuid()  // 'f47ac10b-58cc-4372-a567-0e02b2c3d479'

web - 網路工具

檔案下載、上傳等網路相關工具。

import { web } from 'jg-util'

// 下載檔案
await web.download('https://example.com/image.jpg', './downloads/image.jpg')

// 取得 URL 資料（Base64）
const result = await web.getUrlData('https://example.com/image.jpg')
// { status: true, result: { mimeType: 'image/jpeg', body: 'base64字串...' } }

// 處理檔案上傳（Express middleware）
const result = await web.upload(req, res, {
  uploadPath: './uploads',
  fileSize: 10 * 1000 * 1000,  // 10MB
  fieldName: 'file',
  maxCount: 8
})

🛠️ 開發

# 安裝依賴
npm install

# 執行測試
npm test

# 建置
npm run build