refactor: optimize node api

revilijs · Dec 16, 2024 · 160f07a · 160f07a
1 parent 5569708
commit 160f07a
Show file tree

Hide file tree

Showing 3 changed files with 116 additions and 46 deletions.
diff --git a/docs/docs/api/node-api.md b/docs/docs/api/node-api.md
@@ -36,43 +36,44 @@ title: Node API
   export default demoKit
   ```
 
-### KitOptions
-
-```ts
-interface KitOptions {
-  name: string
-  webFramework?: 'vue'
-  viteOptions?: UserConfig
-  registerService?: (server: ViteDevServer) => void
-  registerCommand: (params: {program: CAC; reviliConfig?: ReviliConfig}) => void
-}
-```
-
 ## getKitData
 
-- Type: `<T extends object>() => Promise<KitData & T>`
+- Type: `<T extends BasicRecord, K extends keyof KitData<T>>(prop?: K): Promise<KitData<T>[K] | null | KitData<T>>`
 - Description: Get current kit data.
 - Example:
   ```typescript
   import { getKitData } from '@revili/helpers/node'
 
-  const kitData = await getKitData()
+  // Get all data
+  const kitData = await getKitData<{ prop: string }>()
+  // Get specific data
+  const propOfKitData = await getKitData<{ prop: string }>('prop')
   ```
 
 ## updateKitData
 
-- Type: `<T extends object>(partialData: Partial<T>) => Promise<void>`
+- Type: `<T extends BasicRecord & Omit<KitData<T>, 'name' | 'installedAt'>>(partialData: Partial<KitData<T>>): Promise<void>`
 - Description: Updates kit data to update only the specified fields.
 - Example:
   ```typescript
   import { updateKitData } from '@revili/helpers/node'
 
-  await updateKitData({
+  await updateKitData<{ version: string; description: string }>({
     version: '1.0.1',
     description: 'The description has been updated!'
   })
   ```
 
+## updateKitDataItem
+
+- Type: `<T extends BasicRecord, K extends Exclude<keyof T, 'name' | 'installedAt'>(key: K, value: T[K]): Promise<void>`
+- Description: Updates kit data to update only the specified field.
+- Example:
+  ```typescript
+  import { updateKitDataItem } from '@revili/helpers/node'
+
+  await updateKitDataItem<{ version: string; description: string }>('version', '1.0.1')
+
 ## useServerSocket
 
 - Type: `(server: ViteDevServer) => WebSocketServer | null`
@@ -97,3 +98,22 @@ interface KitOptions {
 
   export default demoKit
   ```
+
+## ts declaration
+
+```ts
+interface KitOptions {
+  name: string
+  webFramework?: 'vue'
+  viteOptions?: UserConfig
+  registerService?: (server: ViteDevServer) => void
+  registerCommand: (params: {program: CAC; reviliConfig?: ReviliConfig}) => void
+}
+
+type BasicRecord = Record<string | number | symbol, any>
+
+type KitData<T extends BasicRecord = BasicRecord> = {
+  version?: string
+  description?: string
+} & T
+```
diff --git a/docs/zh/docs/api/node-api.md b/docs/zh/docs/api/node-api.md
@@ -36,43 +36,45 @@ title: Node API
   export default demoKit
   ```
 
-### KitOptions
-
-```ts
-interface KitOptions {
-  name: string
-  webFramework?: 'vue'
-  viteOptions?: UserConfig
-  registerService?: (server: ViteDevServer) => void
-  registerCommand: (params: {program: CAC; reviliConfig?: ReviliConfig}) => void
-}
-```
-
 ## getKitData
 
-- 类型：`<T extends object>() => Promise<KitData & T>`
+- 类型：`<T extends BasicRecord, K extends keyof KitData<T>>(prop?: K): Promise<KitData<T>[K] | null | KitData<T>>`
 - 描述：获取当前 kit 的数据。
 - 案例：
   ```typescript
   import { getKitData } from 'revili/node'
 
-  const kitData = await getKitData()
+  // 获取所有数据
+  const kitData = await getKitData<{ prop: string }>()
+  // 获取指定数据
+  const propOfKitData = await getKitData<{ prop: string }>('prop')
   ```
 
 ## updateKitData
 
-- 类型：`<T extends object>(partialData: Partial<T>) => Promise<void>`
+- 类型：`<T extends BasicRecord & Omit<KitData<T>, 'name' | 'installedAt'>>(partialData: Partial<KitData<T>>): Promise<void>`
 - 描述：更新 kit 数据，只更新指定的字段。
 - 案例：
   ```typescript
   import { updateKitData } from 'revili/node'
 
-  await updateKitData({
+  await updateKitData<{ version: string; description: string }>({
     version: '1.0.1',
     description: '更新后的描述'
   })
   ```
 
+## updateKitDataItem
+
+- 类型：`<T extends BasicRecord, K extends Exclude<keyof T, 'name' | 'installedAt'>(key: K, value: T[K]): Promise<void>`
+- 描述：更新 kit 数据，仅更新指定的字段。
+- 案例：
+  ```typescript
+  import { updateKitDataItem } from '@revili/helpers/node'
+
+  await updateKitDataItem<{ version: string; description: string }>('version', '1.0.1')
+  ```
+
 ## useServerSocket
 
 - 类型：`(server: ViteDevServer) => WebSocketServer | null`
@@ -97,3 +99,22 @@ interface KitOptions {
 
   export default demoKit
   ```
+
+## ts 声明
+
+```ts
+interface KitOptions {
+  name: string
+  webFramework?: 'vue'
+  viteOptions?: UserConfig
+  registerService?: (server: ViteDevServer) => void
+  registerCommand: (params: {program: CAC; reviliConfig?: ReviliConfig}) => void
+}
+
+type BasicRecord = Record<string | number | symbol, any>
+
+type KitData<T extends BasicRecord = BasicRecord> = {
+  version?: string
+  description?: string
+} & T
+```
diff --git a/packages/@revili/helpers/src/node/utils/kitData.ts b/packages/@revili/helpers/src/node/utils/kitData.ts
@@ -2,14 +2,19 @@ import fs from 'node:fs'
 import { resolve } from 'node:path'
 import { DATA_DIRS } from '../paths.js'
 import { getReviliConfig } from './reviliData.js'
+import { get } from 'node:http'
+
+/**
+ * Basic object type with any string/number/symbol keys
+ */
+export type BasicRecord = Record<string | number | symbol, unknown>
 
 /**
  * Basic kit data structure
  */
-export interface KitData {
+export interface KitData<T extends BasicRecord & Omit<KitData<T>, 'name' | 'installedAt'> = {}> {
   name: string
   installedAt: string
-  [key: string]: unknown
 }
 
 /**
@@ -80,22 +85,26 @@ export async function initKitData(kitName: string): Promise<void> {
  * Read kit data from data.json
  * @returns The kit data object, or null if data doesn't exist
  */
-export async function getKitData<T extends Omit<KitData, 'name' | 'installedAt'>, K extends keyof (KitData & T)>(
+export async function getKitData<K extends keyof KitData = keyof KitData>(
+  prop: K
+): Promise<KitData[K] | null>
+export async function getKitData<T extends BasicRecord, K extends keyof T = keyof T>(
   prop: K
-): Promise<(KitData & T)[K] | null>
-export async function getKitData<T extends Omit<KitData, 'name' | 'installedAt'>>(): Promise<(KitData & T) | null>
-export async function getKitData<T extends Omit<KitData, 'name' | 'installedAt'>, K extends keyof (KitData & T)>(
+): Promise<T[K] | null>
+export async function getKitData<T extends BasicRecord>(): Promise<KitData<T> | null>
+export async function getKitData(): Promise<KitData<{}> | null>
+export async function getKitData<T extends BasicRecord, K extends keyof KitData<T>>(
   prop?: K
-): Promise<(KitData & T) | (KitData & T)[K] | null> {
+): Promise<KitData<T>[K] | null | KitData<T>> {
   const { activeKit } = await getReviliConfig()
   const dataPath = await getKitDataFilePath(activeKit, 'data.json')
 
   try {
     const content = await fs.promises.readFile(dataPath, 'utf-8')
-    const data = JSON.parse(content) as KitData & T
+    const data = JSON.parse(content) as KitData<T>
 
     if (prop !== undefined) {
-      return data[prop]
+      return data[prop] !== undefined ? data[prop] : null
     }
 
     return data
@@ -110,7 +119,7 @@ export async function getKitData<T extends Omit<KitData, 'name' | 'installedAt'>
  * @param kitName The name of the kit
  * @param data The data object to write
  */
-export async function writeKitData(kitName: string, data: KitData): Promise<void> {
+export async function writeKitData<T extends BasicRecord & Omit<KitData<T>, 'name' | 'installedAt'>>(kitName: string, data: KitData<T>): Promise<void> {
   await ensureKitDataDir(kitName)
   const dataPath = await getKitDataFilePath(kitName, 'data.json')
   await fs.promises.writeFile(dataPath, JSON.stringify(data, null, 2))
@@ -120,16 +129,36 @@ export async function writeKitData(kitName: string, data: KitData): Promise<void
  * Update part of kit data
  * @param partialData Partial data object to merge with existing data
  */
-export async function updateKitData<T extends KitData>(partialData: Partial<T>): Promise<void> {
+export async function updateKitData<T extends BasicRecord & Omit<KitData<T>, 'name' | 'installedAt'>>(partialData: Partial<KitData<T>>): Promise<void> {
   const { activeKit } = await getReviliConfig()
-  const existingData = (await getKitData<T>() ?? {}) as (KitData & T)
+  const existingData = (await getKitData<T>() ?? {}) as KitData<T>
 
-  const newData: T = {
+  const newData: KitData<T> = {
     ...existingData,
     ...partialData,
     name: activeKit,
     installedAt: existingData?.installedAt ?? new Date().toISOString()
-  } as T
+  }
+
+  await writeKitData(activeKit, newData)
+}
+
+/**
+ * Update a single item in kit data
+ * @param key The key to update (cannot be 'name' or 'installedAt')
+ * @param value The new value
+ */
+export async function updateKitDataItem<
+  T extends BasicRecord,
+  K extends Exclude<keyof T, 'name' | 'installedAt'>
+>(key: K, value: T[K]): Promise<void> {
+  const { activeKit } = await getReviliConfig()
+  const existingData = (await getKitData<T>() ?? {}) as KitData<T>
+
+  const newData: KitData<T> = {
+    ...existingData,
+    [key]: value
+  }
 
   await writeKitData(activeKit, newData)
 }