Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/polioan/typescript-notion-formulas
Tool for creating notion table formulas with typescript!
https://github.com/polioan/typescript-notion-formulas
formulas notion notion-database notion-formulas typescript
Last synced: 3 months ago
JSON representation
Tool for creating notion table formulas with typescript!
- Host: GitHub
- URL: https://github.com/polioan/typescript-notion-formulas
- Owner: polioan
- License: mit
- Created: 2023-07-19T06:09:14.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2023-09-10T17:40:12.000Z (over 1 year ago)
- Last Synced: 2024-09-29T19:03:04.173Z (4 months ago)
- Topics: formulas, notion, notion-database, notion-formulas, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/typescript-notion-formulas
- Size: 192 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# typescript notion formulas
[](https://www.npmjs.com/package/typescript-notion-formulas)
[](https://opensource.org/licenses/MIT)
[](https://github.com/polioan)
Tool for creating notion table formulas with TypeScript!
## Warning
Notion has released new formulas 2.0!
They added variables, more property types and multi-line formulas (with tabs and comments too!)
[Whats changed](https://www.notion.so/help/guides/new-formulas-whats-changed)
[Syntax](https://www.notion.so/help/formula-syntax)
So I guess you don't need this tool anymore. Maybe in the future I can transform it to DSL to write formulas in any table like environment (Excel for example)
## Motivations
1. **Readability and maintainability**: Lengthy formulas are hard to read and maintain, leading to confusion and potential errors.
2. **Code reusability**: With complex formulas, it's common to have repetitive sub-expressions and logic. This package helps eliminate code duplication, leading to more concise and efficient formulas.
3. **Error-Prone formulas**: As formulas grow in size, they become prone to errors. A simple typo or misplaced parenthesis can break the entire formula, leading to incorrect results. Debugging such formulas can be time-consuming and frustrating.
4. **Development speed**: By using TypeScript, you benefit from enhanced autocompletion and type-checking features.
## Quick start
### Install
#### npm
```shell
npm i typescript-notion-formulas
```
#### yarn
```shell
yarn add typescript-notion-formulas
```
#### CDN
```html
const { build } = formulas // adds global "formulas" namespace
```
### Basic usage
```ts
import { build } from 'typescript-notion-formulas'
const add = build({ number: 'Number' }).formula(f => {
return f.add(f.prop('number'), 3)
})
console.log(add) // will output - add(prop("number"),3)
// or with destructuring
const add = build({ number: 'Number' }).formula(({ add, prop }) => {
return add(prop('number'), 3)
})
console.log(add) // will output - add(prop("number"),3)
// or unsafe if you don't care about prop types and autocomplete
const add = build().formula(({ add, prop }) => {
return add(prop('number'), 3)
})
console.log(add) // will output - add(prop("number"),3)
```
Default string converter is using JSON.stringify (which is notion using too) so don't go crazy with special characters and white spaces. If you have some special use case - read about complex usage.
Note that notion is sensitive to special characters and with larger formulas it will be hard to copy from console! You can use something like clipboardy to copy the results.
### Prop types
```ts
// import type { PropType } from 'typescript-notion-formulas'
// prop type can be one of 'Date', 'Number', 'Checkbox' or 'Text'
// import type { ConvertableToPropValue } from 'typescript-notion-formulas'
// and you can also use primitive JavaScript values like Date, number, boolean or string - they will be converted to notion, that's will be especially useful with dates
build({ number: 'Number' }).formula(({ add, prop }) => {
return add(prop('number'), 3) // number + number is fine
})
build({ mybirthday: 'Date' }).formula(({ add, prop }) => {
return add(prop('mybirthday'), 3) // will throw at compile time
})
```
### Helpers
I added some helpers for more readable code. (if you can suggest more - reach out to me or submit PR)
```ts
import { build, Helpers } from 'typescript-notion-formulas'
build({ date: 'Date' }).formula(f => {
const { safeToNumber, clamp, dateRange, inRange } = Helpers
return safeToNumber(f.prop('date'))
})
```
### Errors
typescript-notion-formulas checks if your dates and numbers are valid.
```ts
const add = build({ number: 'Number' }).formula(({ add, prop }) => {
return add(prop('number'), 0 / 0)
})
console.log(add) // will output - Invalid number! NaN is not supported.
const add = build({ date: 'Date' }).formula(({ dateBetween, prop }) => {
return dateBetween(prop('date'), new Date('wrong'), 'days')
})
console.log(add) // will output - Invalid date!
```
### Complex usage
```ts
import { Formula, Builder } from 'typescript-notion-formulas'
const f = new Formula({ number: 'Number' })
// don't forget you can use destructuring - const { add, prop } = new Formula({ number: 'Number' })
const addFormula = f.add(f.prop('number'), 2)
const builder = new Builder()
// you can also pass custom string converter - const builder = new Builder({ stringConverter: str => `'${str}'` })
const addAsString = builder.toString(addFormula)
const addAsJson = JSON.stringify(builder.toObj(addFormula))
console.log({ addAsString, addAsJson })
```