Skip to content

Commit f05e525

Browse files
cab-mikeecab-mikee
committed
chore: add stacksjs/docs and cursor rules
1 parent 23b81f9 commit f05e525

12 files changed

+483
-64
lines changed

‎.cursor/rules/code-style.mdc

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
description: Code Style & Structure specifics
3+
globs:
4+
---
5+
## Code Style & Structure
6+
7+
- Write concise, technical TypeScript code with accurate examples in the docblock
8+
- If Bun native modules are available, use them
9+
- Use functional and declarative programming patterns; avoid classes unless needed
10+
- Prefer iteration and modularization over code duplication
11+
- Use descriptive variable names with auxiliary verbs (e.g., `isLoading`, `hasError`)
12+
- Use proper jsdoc comments for functions, types, interfaces, and ensure examples are accurate

‎.cursor/rules/documentation.mdc

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
description: Documentation specific rules
3+
globs: docs/**/*.md
4+
---
5+
## Documentation
6+
7+
- Write documentation for all functions, types, interfaces, and ensure examples are accurate
8+
- The `./docs` directory is where the vitepress markdown documentation is stored
9+
- Make sure to update the docs markdown files

‎.cursor/rules/error-handling.mdc

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: Error Handling and Validation specifics
3+
globs:
4+
---
5+
## Error Handling and Validation
6+
7+
- Prioritize error handling: handle errors and edge cases early
8+
- Use early returns and guard clauses
9+
- Implement proper error logging and user-friendly messages
10+
- Use error boundaries for unexpected errors
11+
- when `neverthrow` is available, ensure errors are typed

‎.cursor/rules/key-conventions.mdc

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: Key code conventions
3+
globs:
4+
---
5+
## Key Conventions
6+
7+
- If there are two equally valid implementations, the browser version should be preferred
8+
- Aim for 100% test coverage
9+
- Avoid usage of `any`
10+
- Reuse eslint-ignore comments where present, unless not needed
11+
- ensure we log everything properly, including for debug reasons

‎.cursor/rules/project-structure.mdc

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: Project structure information
3+
globs:
4+
---
5+
## Project Structure
6+
7+
- the `./src` directory is the source code
8+
- the `./test` directory is the test code
9+
- the `./bin` directory is the command-line code
10+
- you can also call the CLI via `./clarity ...`
11+
- the `./docs` directory is the documentation

‎.cursor/rules/readme.mdc

+241
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
---
2+
description: General information based on the latest ./README.md content
3+
globs:
4+
---
5+
Update it if APIs change:
6+
7+
# ts-spreadsheets
8+
9+
Easily generate spreadsheets, like CSVs and Excel files.
10+
11+
## Features
12+
13+
- Generate CSV & Excel files
14+
- Store spreadsheets to disk
15+
- Download spreadsheets as a Response object
16+
- Simple API for creating and manipulating spreadsheets
17+
- Performant & dependency-free
18+
- Library & CLI support
19+
- Fully typed
20+
21+
## Usage
22+
23+
There are two ways to interact with `ts-spreadsheets`: via the CLI or as a library.
24+
25+
### Library
26+
27+
As a library, you will want to make sure to install it in your project:
28+
29+
```bash
30+
bun install ts-spreadsheets
31+
```
32+
33+
_Now, you can use the library in your project:_
34+
35+
```ts
36+
import { createSpreadsheet, spreadsheet } from 'ts-spreadsheets'
37+
38+
// Create a spreadsheet
39+
const data = {
40+
headings: ['Name', 'Age', 'City'],
41+
data: [
42+
['Chris Breuer', 30, 'Playa Vista'],
43+
['Avery Hill', 25, 'Santa Monica'],
44+
['Danny Johnson', 35, 'San Francisco']
45+
]
46+
}
47+
48+
// Generate and manipulate spreadsheets
49+
50+
// 1. Using createSpreadsheet function
51+
const spreadsheet = createSpreadsheet(data) // defaults to csv
52+
const csvSpreadsheet = createSpreadsheet(data, { type: 'csv' })
53+
const excelSpreadsheet = createSpreadsheet(data, { type: 'excel' })
54+
55+
// Store the spreadsheet to disk
56+
await spreadsheet.store('output.csv')
57+
58+
// Create a download response
59+
const response1 = excelSpreadsheet.download('data.xlsx') // downloads and stores as data.xlsx on your filesystem
60+
61+
// 2. Using spreadsheet object directly, and chain if desired
62+
const csvContent = spreadsheet(data).generateCSV().store('output2.csv')
63+
const csvContent2 = spreadsheet(data).csv().store('output3.csv') // same as above
64+
65+
const excelContent = spreadsheet(data).generateExcel()
66+
await excelContent.store('output3.xlsx')
67+
const response2 = await excelContent.download('output3.xlsx') // downloads and stores as output3.xlsx
68+
69+
// 3. Accessing raw content
70+
const rawCsvContent = spreadsheet(data).csv().getContent()
71+
const rawCsvContent2 = spreadsheet(data).generateCSV().getContent()
72+
const rawExcelContent = spreadsheet(data).excel().getContent()
73+
const rawExcelContent2 = spreadsheet(data).generateExcel().getContent()
74+
75+
console.log('CSV Content:', rawCsvContent)
76+
console.log('Excel Content:', rawExcelContent)
77+
```
78+
79+
### Main Functions
80+
81+
#### spreadsheet(data: Content)
82+
83+
Creates a spreadsheemethods.
84+
85+
- `data`: An object containing `headings` and `data` for the spreadsheet.
86+
87+
Returns an object with the following methods:
88+
89+
- `csv()`: Generates a CSV SpreadsheetWrapper
90+
- `excel()`: Generates an Excel SpreadsheetWrapper
91+
- `store(path: string)`: Stores the spreadsheet to a file
92+
- `generateCSV()`: Generates a CSV SpreadsheetWrapper
93+
- `generateExcel()`: Generates an Excel SpreadsheetWrapper
94+
95+
_Example:_
96+
97+
```typescript
98+
const csvWrapper = await spreadsheet(data).csv() // equivalent to spreadsheet(data).generateCSV()
99+
```
100+
101+
#### createSpreadsheet(data: Content, options?: SpreadsheetOptions)
102+
103+
Creates a SpreadsheetWrapper with the given data and options.
104+
105+
- `data`: An object containing `headings` and `data` for the spreadsheet.
106+
- `options`: Optional. An object specifying the spreadsheet type ('csv' or 'excel').
107+
108+
Returns a SpreadsheetWrapper.
109+
110+
_Example:_
111+
112+
```typescript
113+
const spreadsheet = createSpreadsheet(data, { type: 'csv' })
114+
```
115+
116+
### SpreadsheetWrapper Methods
117+
118+
#### getContent()
119+
120+
Returns the content of the spreadsheet as a string or Uint8Array.
121+
122+
#### download(filename: string)
123+
124+
Creates a download Response for the spreadsheet.
125+
126+
- `filename`: The name of the file to be downloaded.
127+
128+
Returns a Response object.
129+
130+
#### store(path: string)
131+
132+
Stores the spreadsheet to a file.
133+
134+
- `path`: The file path where the spreadsheet will be stored.
135+
136+
Returns a Promise that resolves when the file is written.
137+
138+
### Utility Functions
139+
140+
#### spreadsheet.create(data: Content, options?: SpreadsheetOptions)
141+
142+
Creates a SpreadsheetContent object.
143+
144+
- `data`: An object containing `headings` and `data` for the spreadsheet.
145+
- `options`: Optional. An object specifying the spreadsheet type ('csv' or 'excel').
146+
147+
Returns a SpreadsheetContent object.
148+
149+
#### spreadsheet.generate(data: Content, options?: SpreadsheetOptions)
150+
151+
Generates spreadsheet content based on the given data and o An object containing `headings` and `data` for the spreadsheet.
152+
- `options`: Optional. An object specifying the spreadsheet type ('csv' or 'excel').
153+
154+
Returns a string or Uint8Array representing the spreadsheet content.
155+
156+
#### spreadsheet.generateCSV(content: Content)
157+
158+
Generates a CSV SpreadsheetWrapper.
159+
160+
- `content`: An object containing `headings` and `data` for the spreadsheet.
161+
162+
Returns a SpreadsheetWrapper for CSV, which can be used to chain other methods like `store()` or `download()`.
163+
164+
_Example:_
165+
166+
```typescript
167+
await spreadsheet(data).generateCSV().store('output.csv')
168+
169+
// if one can rely on the file extension to determine the type, you may do this:
170+
await spreadsheet(data).store('output.csv')
171+
```
172+
173+
#### spreadsheet.generateExcel(content: Content)
174+
175+
Generates an Excel SpreadsheetWrapper.
176+
177+
- `content`: An object containing `headings` and `data` for the spreadsheet.
178+
179+
Returns a SpreadsheetWrapper for Excel, which can be used to chain other methods like `store()` or `download()`.
180+
181+
_Example:_
182+
183+
```ts
184+
await spreadsheet(data).store('output.xlsx')
185+
// or
186+
await spreadsheet(data).generateExcel().store('output.xlsx')
187+
```
188+
189+
To view the full documentation, please visit [https://ts-spreadsheets.netlify.app](mdc:https:/ts-spreadsheets.netlify.app).
190+
191+
### CLI
192+
193+
You can also use the CLI to generate spreadsheets from JSON input:
194+
195+
```bash
196+
# Create a spreadsheet from JSON input
197+
spreadsheets create data.json -o output.csv
198+
spreadsheets create data.json --type excel -o output.xlsx
199+
200+
# Convert between formats
201+
spreadsheets convert input.csv output.xlsx
202+
spreadsheets convert input.xlsx output.csv
203+
204+
# Validate JSON input format
205+
spreadsheets validate input.json
206+
```
207+
208+
The input json should follow this format:
209+
210+
```json
211+
{
212+
"headings": ["Name", "Age", "City"],
213+
"data": [
214+
["Chris Breuer", 30, "Playa Vista"],
215+
["Avery Hill", 25, "Santa Monica"],
216+
["Danny Johnson", 35, "San Francisco"]
217+
]
218+
}
219+
```
220+
221+
#### CLI Commands
222+
223+
- `create`: Generate a spreadsheet from JSON input
224+
- Options:
225+
- `-t, --type <type>`: Output type ('csv' or 'excel'), defaults to 'csv'
226+
- `-o, --output <path>`: Output file path
227+
- `convert`: Convert between spreadsheet formats
228+
- Automatically detects format from file extensions
229+
- Supports conversion between CSV and Excel formats
230+
- `validate`: Check if JSON input meets the required format
231+
- Validates structure and data types
232+
- Provides helpful error messages for invalid input
233+
234+
All commands support the `--help` flag for more information:
235+
236+
```bash
237+
spreadsheets --help
238+
spreadsheets create --help
239+
spreadsheets convert --help
240+
spreadsheets validate --help
241+
```

‎.cursor/rules/syntax-formatting.mdc

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
description: Syntax and Formatting specifics
3+
globs:
4+
---
5+
## Syntax and Formatting
6+
7+
- Use the "function" keyword for pure functions
8+
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements
9+
- Make sure everything is properly commented

‎.cursor/rules/testing.mdc

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
description: Testing specifics
3+
globs:
4+
---
5+
## Testing
6+
7+
- Write tests for all functions, types, interfaces, and ensure examples are accurate
8+
- The `./test` directory is where the tests are stored
9+
- Use `bun test` to run the tests
10+
- Use bun native modules for testing from `import { x, y, z } from 'bun:test'`

‎.cursor/rules/typescript.mdc

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
description: TypeScript Usage specifics
3+
globs: docs/**/*.md
4+
---
5+
## TypeScript Usage
6+
7+
- Use TypeScript for all code; prefer interfaces over types
8+
- Avoid enums; use `maps` instead, or `as const`
9+
- Use functional components with TypeScript interfaces

‎README.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -270,9 +270,9 @@ For casual chit-chat with others using this package:
270270

271271
## Postcardware
272272

273-
Two things are true: Stacks OSS will always stay open-source, and we do love to receive postcards from wherever Stacks is used! _We also publish them on our website._
273+
“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where `ts-spreadsheets` is being used! We showcase them on our website too.
274274

275-
Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094 🌎
275+
Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎
276276

277277
## Sponsors
278278

0 commit comments

Comments
 (0)