Skip to content

Typescript README/CONTRIBUTING and export more types #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
+86 −6
Open

Typescript README/CONTRIBUTING and export more types #48

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0516c94
Adds README for developers and rm wasm-pack from npm deps
panzer Aug 4, 2025
961a2ae
Export all available types from the TS package
panzer Aug 4, 2025
0376741
Add in-development note
panzer Aug 6, 2025
e93b7c7
Create CONTRIBUTING.md
panzer Aug 10, 2025
91eda8b
Narrow exports
panzer Aug 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions typescript/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
## Prerequisites

This project uses Rust compiled to WebAssembly, so you'll need to set up the Rust toolchain properly before development.

### Required Tools

1. **Rust via rustup** (recommended over system package managers)
2. **wasm-pack**
3. **Node.js**

### Setup Instructions

#### 1. Install Rust (via rustup)

**Important:** Use rustup rather than system package managers (Homebrew on macOS, apt on Ubuntu, etc.) for better toolchain management.

Install Rust using rustup. Platform specific instructions at [rustup.rs](https://rustup.rs/).

#### 2. Add WebAssembly Target

```bash
rustup target add wasm32-unknown-unknown
```

#### 3. Install wasm-pack

```bash
cargo install wasm-pack
```

#### 4. Verify Installation

```bash
# Check Rust
rustc --version
rustup target list --installed | grep wasm32

# Check wasm-pack
wasm-pack --version

# Verify WASM target is available
rustc --print target-list | grep wasm32-unknown-unknown
```

## Development

### Install Dependencies

From the project root:
```bash
npm install
```

### Playground Development

From the project root:
```bash
npm run playground
```

### Project Structure

- `src/` - Rust source code (extensions to cooklang-rs)
- `pkg/` - Generated WebAssembly files (created by wasm-pack)
- `index.ts` - TypeScript entry point
- `Cargo.toml` - Rust dependencies and configuration
9 changes: 9 additions & 0 deletions typescript/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# @cooklang/cooklang-ts

A TypeScript/JavaScript library for parsing CookLang recipes, built with Rust and WebAssembly.

> [!NOTE]
> Package is under development. What exists here may not be published to NPM yet.

## Contributing
See `CONTRIBUTING.md`
12 changes: 9 additions & 3 deletions typescript/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,10 @@
import { version, Parser } from "./pkg/cooklang_wasm";

export { version, Parser };
/* High Level Types */
export { Parser, Recipe, version } from "./pkg/cooklang_wasm";
export type { ScaledRecipeWithReport } from "./pkg/cooklang_wasm";

/* Types defined by Cooklang syntax */
export { Section, Step, Ingredient, Cookware, Timer } from "./pkg/cooklang_wasm";

/* Parsed base-types */
export { Item, Quantity, Value } from "./pkg/cooklang_wasm";
Comment on lines +5 to +9
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One should be able to access these from the top level ScaledRecipeWithReport. Is it purely out of convenience?

We haven't published yet so there will likely be little breakages until everything is settled. I am more fine with this than the * export at least.


5 changes: 2 additions & 3 deletions typescript/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,6 @@
},
"devDependencies": {
"vite-plugin-wasm": "^3.4.1",
"vitest": "^3.2.3",
"wasm-pack": "^0.13.1"
Copy link
Contributor

@jbolda jbolda Aug 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The downside of switching to wasm-pack installed as a subcommand means that we don't have control over the version that is used. Considering this handles the build, keeping everyone on the same version "automatically" reduces questions around builds running differently in CI vs local vs the last time this function was run.

Was there a specific need to do this? I am not opposed to handling this through Rust, but we should identify the reasoning which prompted the change. It will improve our ability to solve that specific requirement.

Also, I would expect that the tests fail with this change, but they aren't. Presuming that is because we haven't also updated the lockfile. Seems that npm ci doesn't through on devDeps... We should probably ensure that it fails so we can confirm that our local lockfile is current.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did this because when I had wasm-pack included through npm, I had the following error during npm install:

npm error code 1
npm error path /Users/matt/Projects/cooklang-rs/typescript
npm error command failed
npm error command sh -c npm run build-wasm && npm run build
npm error > @cooklang/[email protected] build-wasm
npm error > wasm-pack build --target bundler
npm error Error: spawnSync /Users/matt/Projects/cooklang-rs/node_modules/wasm-pack/binary/wasm-pack Unknown system error -86
npm error     at Object.spawnSync (node:internal/child_process:1120:20)
npm error     at spawnSync (node:child_process:869:24)
npm error     at /Users/matt/Projects/cooklang-rs/node_modules/binary-install/index.js:110:24 {
npm error   errno: -86,
npm error   code: 'Unknown system error -86',
npm error   syscall: 'spawnSync /Users/matt/Projects/cooklang-rs/node_modules/wasm-pack/binary/wasm-pack',
npm error   path: '/Users/matt/Projects/cooklang-rs/node_modules/wasm-pack/binary/wasm-pack',
npm error   spawnargs: [ 'build', '--target', 'bundler' ]
npm error }
npm error npm error Lifecycle script `build-wasm` failed with error:
npm error npm error code 1
npm error npm error path /Users/matt/Projects/cooklang-rs/typescript
npm error npm error workspace @cooklang/[email protected]
npm error npm error location /Users/matt/Projects/cooklang-rs/typescript
npm error npm error command failed
npm error npm error command sh -c wasm-pack build --target bundler

I'm on macOS 15.5, node v22.17.1, npm 10.9.2. Installing wasm-pack via cargo worked for me.

don't have control over the version that is used

What do you think about using something like cargo install wasm-pack --version 0.13.1?

I would expect that the tests fail with this change, but they aren't

I think I see what you're saying. I'll try one commit with an updated lockfile without the wasm-pack dev dep and see if it fails. I wonder if we would need to add a cargo install command to the GH Action

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, have you installed rosetta? Is this a new computer? 86 is an unknown arch error from what I understand.

Using this is slightly better...

cargo install wasm-pack --version 0.13.1

But it still means that every user needs to explicitly upgrade when we tell them to upgrade. Also isn't great if they use it in other projects. I wonder if we can manage it through the Cargo.toml? I don't think we could in the past, but haven't looked recently.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we create an issue to follow up on this specifically. It should work with this setup, but also I am personally fine with shifting it elsewhere if we can maintain a consistent version still. Seems like we need more digging though and I don't want to block the PR on this.

"vitest": "^3.2.3"
}
}
}