tests->test + add examples/ and npm run examples (#27)

* tests->test + add examples/ and npm run examples

* export more types, and edit README

* add github action for typedoc

* fix docs + change lint scripts + adapt ci action

Author: severo

.github/workflows/ci.yml

@@ -13,19 +13,26 @@ jobs:
       - run: npm ci
       - run: npm run build
 
-  lint:
+  eslint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - run: npm ci
-      - run: npm run lint
+      - run: npm run lint:eslint
 
-  typecheck:
+  lint-types:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - run: npm ci
-      - run: npm run typecheck
+      - run: npm run lint:types
+
+  lint-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npm run lint:docs
 
   test-node:
     runs-on: ubuntu-latest

.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: TSDoc Actions
+
+on:
+  push:
+    # Trigger deployment only on pushes to the main branch
+    branches:
+      - main
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    name: Deploy Documentation
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 25
+          cache: "npm"
+
+      - name: TSDoc Action
+        uses: erikyo/tsdoc-action@v1
+        with:
+          source_dir: ./src/*
+          output_dir: ./docs
+          front_page: README.md
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          # Upload entire repository
+          path: "./docs"
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -5,3 +5,5 @@ dist
 
 # Vitest
 /coverage/
+
+/docs/

CHANGELOG.md

@@ -15,7 +15,7 @@
 
 ## [0.0.7]
 
-- export toURL utility function
+- export toBlobURL utility function
 
 ## [0.0.6]
 

README.md

@@ -9,14 +9,6 @@
 
 Fetch and parse ranges of CSV file.
 
-## Early version
-
-This is an early version. The API may change completely:
-
-- until version 0.1.0, breaking changes may be introduced at any time.
-- from version 0.1.0 to 1.0.0, breaking changes will be introduced only in minor versions.
-- from version 1.0.0, breaking changes will be introduced only in major versions.
-
 ## Install
 
 ```bash
@@ -37,6 +29,14 @@ console.log(rows)
 // Output: [ [ 'A', 'B', 'C' ], [ 'X', 'Y', 'Z' ] ]
 ```
 
+## Early version
+
+This is an early version. The API may change completely:
+
+- until version 0.1.0, breaking changes may be introduced at any time.
+- from version 0.1.0 to 1.0.0, breaking changes will be introduced only in minor versions.
+- from version 1.0.0, breaking changes will be introduced only in major versions.
+
 ## Thanks
 
 The code is heavily inspired by [Papaparse](https://www.papaparse.com/).

eslint.config.js

@@ -30,11 +30,12 @@ export default defineConfig([
       'simple-import-sort/exports': 'error',
       'jsdoc/require-yields-type': 'off',
       'jsdoc/require-param-type': 'off',
+      'jsdoc/require-property-type': 'off',
       'jsdoc/require-returns-type': 'off',
     },
   },
   {
-    files: ['tests/*.ts'],
+    files: ['examples/**/*.ts', 'test/**/*.ts'],
     rules: {
       'jsdoc/require-jsdoc': 'off',
     },

examples/examples.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+
+import { type ParseResult, parseURL } from '../src'
+
+describe('README examples', () => {
+  it('parses a remote CSV file', async () => {
+    const rows = []
+    for await (const { row } of parseURL('https://data.source.coop/severo/csv-papaparse-test-files/sample.csv')) {
+      rows.push(row)
+    }
+    expect(rows).toEqual([['A', 'B', 'C'], ['X', 'Y', 'Z']])
+  })
+
+  it('parses a remote CSV, and we can use Array.fromAsync for convenience', async () => {
+    // The test might fail if fromAsync is not yet available in the node.js version running the tests
+
+    // @ts-expect-error ts(2345) - fromAsync is available now
+    const rows = await Array.fromAsync(
+      parseURL('https://data.source.coop/severo/csv-papaparse-test-files/sample.csv'),
+      async (result: ParseResult) => result.row,
+    )
+    expect(rows).toEqual([['A', 'B', 'C'], ['X', 'Y', 'Z']])
+  })
+})