docs: revise docs

Gumball12 · Mar 11, 2024 · 54ad93e · 54ad93e
1 parent d1e3d1e
commit 54ad93e
Showing 1 changed file with 81 additions and 48 deletions.
diff --git a/README.md b/README.md
@@ -8,50 +8,7 @@
 
 > Check out the [Online Sandbox](https://gumball12.github.io/google-spreadsheet-dts/)!
 
-This library **automatically generates TypeScript types (`*.d.ts`) by parsing Google Sheets**. It is useful for event tracking systems(like Mixpanel and Google Analytics) or managing internationalized(I18N) data in Google Sheets. Here's an example:
-
-Google Sheet:
-
-| Key                           | Property           | Type                           |
-| ----------------------------- | ------------------ | ------------------------------ |
-| click_conversation_data       | conversation_id    | string                         |
-|                               | created_at         | Date                           |
-|                               | agent_type         | string                         |
-|                               | status             | StatusEnum                     |
-|                               | generate_position  | 'conversation' \| 'playground' |
-| click_message_feedback_button | conversation_id    | string                         |
-|                               | message_id         | string                         |
-|                               | generated_position | 'conversation' \| 'playground' |
-
-Generated TypeScript types:
-
-```ts
-// GoogleSheets.d.ts
-
-// Generated by google-spreadsheet-dts
-/* eslint-disable */
-/* prettier-ignore */
-// @ts-nocheck
-// noinspection JSUnusedGlobalSymbols
-import { StatusEnum } from './StatusEnum';
-export {};
-declare global {
-  export interface GoogleSheets {
-    click_conversation_data: {
-      conversation_id: string;
-      created_at: Date;
-      agent_type: string;
-      status: StatusEnum;
-      generate_position: 'conversation' | 'playground';
-    };
-    click_message_feedback_button: {
-      conversation_id: string;
-      message_id: string;
-      generated_position: 'conversation' | 'playground';
-    };
-  }
-}
-```
+This library **automatically generates TypeScript types (`*.d.ts`) by parsing Google Sheets**. It is useful when using Google Sheets to manage event tracking systems (such as Mixpanel and Google Analytics) or internationalization (I18N) data.
 
 ## 💫 Features
 
@@ -98,8 +55,6 @@ import { generateDtsFile } from 'google-spreadsheet-dts';
 import { resolve } from 'node:path';
 import { publicGoogleSheetsParser } from 'google-spreadsheet-dts/parser';
 
-import PublicGoogleSheetsParser from 'public-google-sheets-parser';
-
 generateDtsFile({
   name: 'GoogleSheets',
   directory: resolve(__dirname, '../src'),
@@ -142,8 +97,6 @@ const { generateDtsFile } = require('google-spreadsheet-dts');
 const { resolve } = require('node:path');
 const { publicGoogleSheetsParser } = require('google-spreadsheet-dts/parser');
 
-const PublicGoogleSheetsParser = require('public-google-sheets-parser');
-
 generateDtsFile({
   name: 'GoogleSheets',
   directory: resolve(__dirname, '../src'),
@@ -223,12 +176,21 @@ export const event = <T extends GoogleSheets, K extends keyof T>({
   // ...
 };
 
+// ✅ OK
 event({
   action: 'click_conversation_data',
   properties: {
     generate_position: 'conversation',
   },
 });
+
+// ❌ Compile Error
+event({
+  action: 'click_conversation_data',
+  properties: {
+    generate_position: 'invalid', // TSError: Type '"invalid"' is not assignable to type '"conversation" | "playground"'.
+  },
+});
 ```
 
 ## 📚 API
@@ -292,6 +254,77 @@ type Import = {
     - `name`: Name of the type to import.
     - `from`: File path to import the type from.
 
+## 👉 So, why should I use google-spreadsheet-dts?
+
+- **Type Safety**: You can statically validate the data at compile time.
+- **Maintainability**: You can anticipate the impact of changes to the sheet data in advance.
+- **Productivity**: You can write code that uses data more easily.
+
+### Without google-spreadsheet-dts
+
+```ts
+export const event = ({
+  action,
+  properties,
+}: {
+  action: string;
+  properties: Record<string, unknown>;
+}) => {
+  // ...
+};
+
+// ✅ OK
+event({
+  action: 'click_conversation_data',
+  properties: {
+    generate_position: 'conversation',
+  },
+});
+
+// ⚠️ Compile OK but Unexpected behavior
+event({
+  action: 'click_conversation_data',
+  properties: {
+    // 'invalid' is not a valid value for 'generate_position'
+    generate_position: 'invalid',
+  },
+});
+```
+
+### With google-spreadsheet-dts
+
+```ts
+export const event = <T extends GoogleSheets, K extends keyof T>({
+  action,
+  properties,
+}: {
+  action: K;
+  properties: Partial<T[K]>;
+}) => {
+  // ...
+};
+
+// ✅ OK
+event({
+  action: 'click_conversation_data',
+  properties: {
+    generate_position: 'conversation',
+  },
+});
+
+// ❌ Compile Error
+event({
+  action: 'click_conversation_data',
+  properties: {
+    generate_position: 'invalid', // TSError: Type '"invalid"' is not assignable to type '"conversation" | "playground"'
+  },
+});
+```
+
+## ✋ Limitations
+
+- Not Production Ready: This library is still in the early stages of development. Please use it with caution.
+
 ## License
 
 [MIT](./LICENSE) @Gumball12