{"id":20140405,"url":"https://github.com/gumball12/google-spreadsheet-dts","last_synced_at":"2025-04-09T18:33:21.487Z","repository":{"id":224381621,"uuid":"760409695","full_name":"Gumball12/google-spreadsheet-dts","owner":"Gumball12","description":"[WIP] Validate Google Spreadsheet at compile time 👌","archived":false,"fork":false,"pushed_at":"2025-03-11T09:00:35.000Z","size":1720,"stargazers_count":11,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-05T00:34:24.112Z","etag":null,"topics":["dts","google","google-spreadsheet","google-spreadsheet-api","google-spreadsheet-dts","spreadsheet","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/google-spreadsheet-dts","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Gumball12.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-20T11:17:42.000Z","updated_at":"2025-03-11T09:00:37.000Z","dependencies_parsed_at":"2024-02-25T17:20:15.511Z","dependency_job_id":"bc556570-513a-4fdc-b200-2cdffdcb5296","html_url":"https://github.com/Gumball12/google-spreadsheet-dts","commit_stats":null,"previous_names":["gumball12/google-spreadsheet-dts"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gumball12%2Fgoogle-spreadsheet-dts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gumball12%2Fgoogle-spreadsheet-dts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gumball12%2Fgoogle-spreadsheet-dts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gumball12%2Fgoogle-spreadsheet-dts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Gumball12","download_url":"https://codeload.github.com/Gumball12/google-spreadsheet-dts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248087957,"owners_count":21045620,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dts","google","google-spreadsheet","google-spreadsheet-api","google-spreadsheet-dts","spreadsheet","typescript"],"created_at":"2024-11-13T21:51:33.596Z","updated_at":"2025-04-09T18:33:21.460Z","avatar_url":"https://github.com/Gumball12.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# google-spreadsheet-dts\n\n![npm bundle size](https://img.shields.io/bundlephobia/minzip/google-spreadsheet-dts) ![NPM Downloads](https://img.shields.io/npm/dm/google-spreadsheet-dts) ![NPM Version](https://img.shields.io/npm/v/google-spreadsheet-dts)\n\n[![ci](https://github.com/Gumball12/google-spreadsheet-dts/actions/workflows/ci.yaml/badge.svg)](https://github.com/Gumball12/google-spreadsheet-dts/actions/workflows/ci.yaml) [![publish](https://github.com/Gumball12/google-spreadsheet-dts/actions/workflows/publish-npm.yaml/badge.svg)](https://github.com/Gumball12/google-spreadsheet-dts/actions/workflows/publish-npm.yaml) [![codecov](https://codecov.io/gh/Gumball12/google-spreadsheet-dts/graph/badge.svg?token=8uuKMCW2bk)](https://codecov.io/gh/Gumball12/google-spreadsheet-dts) [![changelog](https://img.shields.io/badge/CHANGELOG-gray)](./CHANGELOG.md)\n\n![logo](./docs/logo-extended.png)\n\n\u003e Check out the [Online Sandbox](https://gumball12.github.io/google-spreadsheet-dts/)!\n\nThis 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.\n\n## 💫 Features\n\n- [Parser presets](./src/parser) and Generate types(`*.d.ts`) for **public and private Google Sheets**\n- Customizable type and file name\n- Import types from other files\n\n### Performance\n\n```\nMacBook Air (M1, 2020, 16GB)\nNode.js v20.10.0\n\n$ pnpm bench\n\nname                               hz      min     max     mean      p75     p99    p995    p999     rme  samples\ncreateDtsBody :: 100000 Rows  10.6335  76.2435  116.52  94.0420  98.9237  116.52  116.52  116.52  ±9.26%       10   fastest\n```\n\n[performance.bench.ts](./src/__tests__/performance.bench.ts)\n\n## 📦 Install\n\n```bash\nnpm i --save-dev google-spreadsheet-dts\nyarn add -D google-spreadsheet-dts\npnpm add -D google-spreadsheet-dts\n```\n\n## 🚀 Usage\n\n### 1. Select a Google Sheets parser preset\n\ngoogle-spreadsheet-dts provides parser presets for public and private Google Sheets. Check out the parser presets [here](./src/parser/README.md). You can also create custom parsers if needed.\n\n### 2. Generate types with Google Sheets parser\n\nCreate the file scripts/generate-google-sheets-dts.ts. Here we use the parser preset [`publicGoogleSheetsParser`](./src/parser/publicGoogleSheetsParser.ts). You can check the sheet content [here](https://docs.google.com/spreadsheets/d/1j23zhzHcPd_LzDQ7uPrXgMJfPoZYs289boUKoKnAjUo/edit#gid=0).\n\n```ts\n// scripts/generate-google-sheets-dts.ts\n\nimport { generateDtsFile } from 'google-spreadsheet-dts';\nimport { resolve } from 'node:path';\nimport { publicGoogleSheetsParser } from 'google-spreadsheet-dts/parser';\n\ngenerateDtsFile({\n  name: 'GoogleSheets',\n  directory: resolve(__dirname, '../src'),\n\n  createDtsBody: {\n    // Define the types to import in the dts file\n    importTypes: [\n      {\n        name: 'StatusEnum',\n        from: './StatusEnum',\n      }\n    ]\n  }\n\n  parser: publicGoogleSheetsParser(\n    {\n      spreadsheetId: '1j23zhzHcPd_LzDQ7uPrXgMJfPoZYs289boUKoKnAjUo',\n    },\n    {\n      path: ['Key', 'Property'],\n      typeName: 'Type',\n    },\n  ),\n});\n```\n\nNow, the types can be generated with the following command. The types are generated in the file src/GoogleSheets.ts.\n\n```bash\nts-node scripts/generate-google-sheets-dts.ts\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eUsing JavaScript\u003c/summary\u003e\n\n```js\n// scripts/generate-google-sheets-dts.js\n\nconst { generateDtsFile } = require('google-spreadsheet-dts');\nconst { resolve } = require('node:path');\nconst { publicGoogleSheetsParser } = require('google-spreadsheet-dts/parser');\n\ngenerateDtsFile({\n  name: 'GoogleSheets',\n  directory: resolve(__dirname, '../src'),\n\n  createDtsBody: {\n    importTypes: [\n      {\n        name: 'StatusEnum',\n        from: './StatusEnum',\n      }\n    ]\n  }\n\n  parser: publicGoogleSheetsParser(\n    {\n      spreadsheetId: '1j23zhzHcPd_LzDQ7uPrXgMJfPoZYs289boUKoKnAjUo',\n    },\n    {\n      path: ['Key', 'Property'],\n      typeName: 'Type',\n    },\n  ),\n});\n```\n\n```bash\nnode scripts/generate-google-sheets-dts.js\n```\n\n\u003c/details\u003e\n\n### 3. Use generated types\n\nThe above command generates the src/GoogleSheets.d.ts file as follows:\n\n```ts\n// src/GoogleSheets.d.ts\n\n// Generated by google-spreadsheet-dts\n/* eslint-disable */\n/* prettier-ignore */\n// @ts-nocheck\n// noinspection JSUnusedGlobalSymbols\nimport { StatusEnum } from './StatusEnum';\nexport {};\ndeclare global {\n  export interface GoogleSheets {\n    click_conversation_data: {\n      conversation_id: string;\n      created_at: Date;\n      agent_type: string;\n      status: StatusEnum;\n      generate_position: 'conversation' | 'playground';\n    };\n    click_message_feedback_button: {\n      conversation_id: string;\n      message_id: string;\n      generated_position: 'conversation' | 'playground';\n      my_test: string | 'string';\n    };\n  }\n}\n```\n\nThe generated types are now available for use. Since the types are declared globally, you can use them without importing.\n\n```ts\n// src/my-event.ts\n\nexport const event = \u003cT extends GoogleSheets, K extends keyof T\u003e({\n  action,\n  properties,\n}: {\n  action: K;\n  properties: Partial\u003cT[K]\u003e;\n}) =\u003e {\n  // ...\n};\n\n// ✅ OK\nevent({\n  action: 'click_conversation_data',\n  properties: {\n    generate_position: 'conversation',\n  },\n});\n\n// ❌ Compile Error\nevent({\n  action: 'click_conversation_data',\n  properties: {\n    generate_position: 'invalid', // TSError: Type '\"invalid\"' is not assignable to type '\"conversation\" | \"playground\"'.\n  },\n});\n```\n\n## 📚 API\n\n### `generateDtsFile`\n\n```ts\nfunction generateDtsFile(params: GenerateDtsFileParams): Promise\u003cvoid\u003e;\n\ntype Params = {\n  name: string;\n  directory: string;\n  parser: Parser;\n  options?: GenerateDtsFileOptions;\n};\n\ntype Parser = () =\u003e Promise\u003cobject\u003e | object;\n\ntype GenerateDtsFileOptions = Partial\u003c{\n  fileName: string;\n  output: (dts: string) =\u003e unknown;\n  createDtsBody: CreateDtsOptions;\n}\u003e;\n```\n\n- `name`: Name of the type. If `options.fileName` is not specified, it will also be used as the file name.\n- `directory`: Directory where the generated type file will be located.\n- `parser`: A function that defines how to parse the Google Sheets. You can use [parser presets](./src/parser).\n- `options`\n  - `fileName`: Name of the type file to generate. The default is the `name` parameter.\n  - `output`: A function that defines how to use the generated types. By default, it saves to a file.\n  - `createDtsBody`: Options to customize the contents of the generated type file. See the [`createDtsBody`](#createdtsbody) section for details.\n\nTo create a custom parser, see the [Writing a custom parser](./src/parser/README.md#writing-a-custom-parser) section.\n\n### `createDtsBody`\n\n```ts\nfunction createDtsBody(\n  name: string,\n  object: object,\n  options?: CreateDtsOptions,\n): string;\n\ntype CreateDtsOptions = Partial\u003c{\n  defaultType: string;\n  importTypes: Import[];\n}\u003e;\n\ntype Import = {\n  name: string;\n  from: string;\n};\n```\n\n- `name`: Name of the type.\n- `object`: Content for the types.\n- `options`\n  - `defaultType`: Type to use when the sheet type is an empty string, `undefined`, or `null`. Default is `any`.\n  - `importTypes`: Types to import from inside the file.\n    - `name`: Name of the type to import.\n    - `from`: File path to import the type from.\n\n## 👉 So, why should I use google-spreadsheet-dts?\n\n- **Type Safety**: You can statically validate the data at compile time.\n- **Maintainability**: You can anticipate the impact of changes to the sheet data in advance.\n- **Productivity**: You can write code that uses data more easily.\n\n### Without google-spreadsheet-dts\n\n```ts\nexport const event = ({\n  action,\n  properties,\n}: {\n  action: string;\n  properties: Record\u003cstring, unknown\u003e;\n}) =\u003e {\n  // ...\n};\n\n// ✅ OK\nevent({\n  action: 'click_conversation_data',\n  properties: {\n    generate_position: 'conversation',\n  },\n});\n\n// ⚠️ Compile OK but Unexpected behavior\nevent({\n  action: 'click_conversation_data',\n  properties: {\n    // 'invalid' is not a valid value for 'generate_position'\n    generate_position: 'invalid',\n  },\n});\n```\n\n### With google-spreadsheet-dts\n\n```ts\nexport const event = \u003cT extends GoogleSheets, K extends keyof T\u003e({\n  action,\n  properties,\n}: {\n  action: K;\n  properties: Partial\u003cT[K]\u003e;\n}) =\u003e {\n  // ...\n};\n\n// ✅ OK\nevent({\n  action: 'click_conversation_data',\n  properties: {\n    generate_position: 'conversation',\n  },\n});\n\n// ❌ Compile Error\nevent({\n  action: 'click_conversation_data',\n  properties: {\n    generate_position: 'invalid', // TSError: Type '\"invalid\"' is not assignable to type '\"conversation\" | \"playground\"'\n  },\n});\n```\n\n## ✋ Limitations\n\n- Not Production Ready: This library is still in the early stages of development. Please use it with caution.\n\n## License\n\n[MIT](./LICENSE) @Gumball12\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgumball12%2Fgoogle-spreadsheet-dts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgumball12%2Fgoogle-spreadsheet-dts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgumball12%2Fgoogle-spreadsheet-dts/lists"}