sheets-lucid

面向 Vue 3 的 Google Sheets ORM，靈感來自 AdonisJS Lucid。提供 Schema 驗證、Model/Query Builder、生命週期 Hooks 與雙認證 (API Key + OAuth2)。

安裝

npm install sheets-lucid gapi-script

vue 建議作為 peer 依賴 (^3.3 || ^3.4 || ^3.5)。

初始化步驟

1. 在 Google Cloud 啟用「Sheets API」，建立 OAuth 2.0 用戶端 (Web) 及 API Key，允許的來源包含本地開發網址。
2. 建立試算表，記下 Spreadsheet ID (網址中的 {SPREADSHEET_ID}) 並在第一列放入欄位名稱。
3. 設定環境變數：

# .env.local (Vite 範例)
VITE_API_KEY=your-sheets-api-key
VITE_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
VITE_SPREADSHEET_ID=your-spreadsheet-id

配置範例

sheets-orm.config.ts

import { Schema, defineConfig } from 'sheets-lucid'

export default defineConfig({
  spreadsheetId: import.meta.env.VITE_SPREADSHEET_ID,
  auth: {
    apiKey: import.meta.env.VITE_API_KEY,
    oauth: {
      clientId: import.meta.env.VITE_GOOGLE_CLIENT_ID,
      scopes: [
        'https://www.googleapis.com/auth/spreadsheets',
        'https://www.googleapis.com/auth/drive.readonly'
      ],
      // token: { expiresIn: 8 * 60 * 60, refreshThreshold: 10 * 60 * 1000 }
    },
    preferredMode: 'api_key' // 讀取優先用 API Key，寫入時自動升級 OAuth2
  },
  schemas: {
    users: Schema.create({
      id: Schema.number().primary().autoIncrement(),
      name: Schema.string().required(),
      email: Schema.string().required().unique().email(),
      status: Schema.enum(['active', 'inactive'] as const).default('active'),
      createdAt: Schema.dateTime(),
      updatedAt: Schema.dateTime(),
      deletedAt: Schema.dateTime().nullable()
    })
  },
  cache: { enabled: false, ttl: 5 * 60 * 1000 },
  debug: true,
  pagination: { perPage: 20, maxPerPage: 100 }
})

在 Vue 啟動

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import config from './config/sheets-orm.config'
import { createSheetsORM } from 'sheets-lucid'

const app = createApp(App)
const sheetsORM = createSheetsORM(config)

app.use(sheetsORM) // 提供 $db、useDatabase/useAuth
app.mount('#app')

定義 Model

// models/User.ts
import { BaseModel, column, beforeSave } from 'sheets-lucid'

export default class User extends BaseModel {
  static table = 'users'
  static softDeletes = true

  @column({ isPrimary: true }) declare id: number
  @column() declare name: string
  @column() declare email: string
  @column() declare status: 'active' | 'inactive'
  @column.dateTime({ autoCreate: true }) declare createdAt: Date
  @column.dateTime({ autoCreate: true, autoUpdate: true }) declare updatedAt: Date
  @column.dateTime() declare deletedAt: Date | null

  static scopes = {
    active: (query) => query.where('status', 'active')
  }

  @beforeSave()
  touchTimestamps() {
    if (this.isNew) this.createdAt = new Date()
    this.updatedAt = new Date()
  }
}

查詢與認證

import { useAuth } from 'sheets-lucid'
import User from './models/User'

const { isAuthenticated, signIn, signOut } = useAuth()
await signIn('oauth2') // 需要寫入時呼叫；讀取可用 API Key

const users = await User.query().apply('active').orderBy('createdAt', 'desc').paginate(1, 20)
const john = await User.find(1)
if (john) {
  john.status = 'inactive'
  await john.save()
}

useDatabase() 也可直接取得 db.from('table') Query Builder。

套件開發/發布

• 產生編譯輸出：cd sheets-lucid && npm install && npm run build
• dist/ 會輸出 ESM 與型別檔案。
• 若要發布：npm login 之後執行 npm publish (需擁有 lu7766lu7766 帳號登入權限)。

附註

套件依賴瀏覽器環境與 Google gapi，請在前端專案中使用並確認 OAuth 同意畫面與來源網域皆已設定。