Merge pull request #46 from STRd6/types

Types; convert to civet

Author: STRd6

.github/workflows/build.yml

@@ -7,17 +7,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
 
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v4
 
-    - name: Setup Node.js 16.x
-      uses: actions/setup-node@v2
+    - name: Setup Node.js 20.x
+      uses: actions/setup-node@v4
       with:
         cache: yarn
-        node-version: 16.x
+        node-version: 20.x
 
     - name: Install and Test
       run: |
         yarn
+        yarn build
         yarn test
 
     - name: Coveralls

.gitignore

@@ -6,3 +6,4 @@ dist/
 gh-pages/
 node_modules/
 test/samples/*.js
+test/fixtures/out/

.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "phil294.coffeesense",
+    "DanielX.hera"
+  ]
+}

NOTES.md

@@ -0,0 +1,81 @@
+TypeScript
+==========
+
+esbuild is a real stickler with extensions so it is necessary to require "parser.hera".
+TypeScript then needs a parser.hera.d.ts to work with CoffeeSense. Alternatively
+an esbuild resolver plugin could be used.
+
+So far the clean way of handling it is to declare all the types in `./types/`
+and import then `export = SomeType` in the individual .d.ts files adjacent
+to the sources.
+
+Building with `tsc` is not necessary if we're only using CoffeeScript sources
+since `./types/main.d.ts` is pointed to by the `type` field in `package.json`.
+If there are other TypeScript sources then `tsc` will need to be involved in the
+build process.
+
+`export =` vs `export default`
+---
+
+`export = Something` is necessary for `Something = require('...')` to get picked
+up properly. `export default Something` works with `{default:Something} = require...`
+
+`export =` cannot be used with `export {something}`.
+
+Since all the modern tools are moving in the direction of ES6 import/export it
+may simplify integration with some tools to also move in that direction.
+
+Ambient Declarations
+---
+
+A typescript file that exports will ignore ambient `declare` statements. In
+order to have ambient they must all be `declare`.
+
+Ambient declarations also cannot import other types but a work around is to use
+`declare global` and put vars inside there. See [./types/ambient.d.ts](./types/ambient.d.ts)
+
+Namespaces as types
+---
+
+Cannot use namespace 'Observable' as type.
+
+use `typeof Observable`
+
+TypeDoc
+-------
+
+TypeDoc seems to work pretty good by default when using `.ts` files with ES6
+style exports.
+
+TypeDoc and other more modern tools strongly prefer ES6 module imports/exports.
+`.d.ts` files prefer it (there is no way to both `export =` and also have named
+exports even if those exports are just types).
+
+JSDoc
+---
+
+JS written with JSDoc type annotations and compiled with `tsc -d --allowJs` will
+output type declarations.
+
+CoffeeSense + TypeScript
+---
+
+VSCode Intellisense is the primary documentation target. That means that the
+docs should be optimized for how things appear in the IDE. 2nd target is a
+standalone website generated by TypeDoc or some other tool. Still need to test
+TypeDoc with a .coffee -> .js -> .d.ts -> TypeDoc pipeline and see how it goes.
+
+Need to set `checkJs` to true or add `#@ts-check` to enable type checking in
+CoffeeSense.
+
+It is possible to alias a bunch of imported types at the top to make using
+comments for inline types easier inside the file.
+
+```coffee
+###*
+@typedef {import("../types/types").Element} El
+@typedef {import("../types/types").Context} Context
+@typedef {import("../types/types").JadeletAttribute} JadeletAttribute
+@typedef {import("../types/types").JadeletAST} JadeletAST
+###
+```

TODO.md

@@ -0,0 +1,17 @@
+TODO
+====
+
+- [ ] Explore Custom elements
+- [ ] Optionally pass `document` when rendering?
+- [x] Explore adding TypeScript typings
+  - [x] declare "jadelet/esbuild-plugin" module
+  - [x] Figure out secrets of CoffeeSense and workspace setup
+  - [x] Publishing types
+- [x] esbuild plugin
+- [x] Use esbuild for publishing
+  - [x] main
+  - [x] cli
+  - [x] browser
+- [x] Update to @danielx/observable
+- [x] Update register
+- [x] Update to hera 0.7.3-pre.3

build/build.civet

@@ -0,0 +1,49 @@
+esbuild from esbuild
+civetPlugin from @danielx/civet/esbuild
+heraPlugin from @danielx/hera/esbuild-plugin
+
+esbuild.build
+  entryPoints: ['source/index.civet']
+  format: 'esm'
+  tsconfig: "./tsconfig.json"
+  bundle: true
+  sourcemap: true
+  outdir: 'dist/'
+  outExtension:
+    ".js": ".mjs"
+  plugins: [
+    civetPlugin
+      ts: "civet"
+      emitDeclaration: true
+    heraPlugin
+      module: true
+  ]
+.catch ->
+  process.exit 1
+
+esbuild.build
+  entryPoints: ['source/index.civet']
+  format: 'cjs'
+  tsconfig: "./tsconfig.json"
+  bundle: true
+  sourcemap: true
+  outdir: 'dist/'
+  plugins: [
+    civetPlugin
+      ts: "civet"
+    heraPlugin
+      module: true
+  ]
+.catch ->
+  process.exit 1
+
+esbuild.build({
+  entryPoints: ['source/cli.civet']
+  platform: 'node'
+  format: 'cjs'
+  outfile: 'dist/cli.js'
+  plugins: [
+    civetPlugin
+      ts: "civet"
+  ]
+}).catch -> process.exit 1

build/build.sh

@@ -0,0 +1,23 @@
+#! /bin/bash
+
+set -eoux pipefail
+shopt -s globstar
+
+rm -rf dist
+
+# build
+civet build/build.civet
+
+# adjust .d.ts files
+for f in dist/**/*.civet.d.ts; do
+  # replace all .civet imports with .js
+  sed -i 's/\.civet"/.js"/g' "$f"
+  mv "$f" "${f%.civet.d.ts}.d.ts"
+done
+
+# cli
+sed -i 's/\.civet"/.js"/g' dist/cli.js
+BIN="dist/jadelet"
+echo "#!/usr/bin/env node" | cat - dist/cli.js > "$BIN"
+chmod +x "$BIN"
+rm dist/cli.js

build/plugin-test.civet

@@ -0,0 +1,19 @@
+esbuild from esbuild
+jadeletPlugin from ../esbuild-plugin.js
+path from path
+
+root := path.resolve()
+
+esbuild.build
+  entryPoints: ['test/fixtures/esbuild.js']
+  globalName: "Bundle"
+  bundle: true
+  sourcemap: true
+  external: ["jadelet"]
+  platform: 'browser'
+  outfile: 'test/fixtures/out/build.js'
+  plugins: [
+    jadeletPlugin
+      runtime: `require(${JSON.stringify(root)})`
+  ]
+.catch -> process.exit 1