|
| 1 | +--- |
| 2 | +name: squint |
| 3 | +description: "Squint ClojureScript development — writing Squint code, compilation, REPL workflow, debugging, and tooling. Use when: working with Squint projects, planning, writing, or reviewing Squint code, .cljs files compiled to .mjs, Squint REPL sessions, debugging compiled output, checking whether clojure.core functions exist in Squint, or setting up Squint builds. Use whenever you are using Backseat Driver tools with Squint." |
| 4 | +--- |
| 5 | + |
| 6 | +# Squint Skill |
| 7 | + |
| 8 | +Squint is a ClojureScript-syntax compiler that emits ES module JavaScript. It is NOT standard ClojureScript (shadow-cljs) and NOT SCI — it has fundamentally different semantics for data structures, keywords, and async. The Clojure skill's S3 Dialects section provides cross-dialect comparison; this skill provides full Squint operational depth. |
| 9 | + |
| 10 | +## Compilation Model |
| 11 | + |
| 12 | +Squint compiles `.cljs` files to ES modules (`.mjs`) via configuration in `squint.edn`: |
| 13 | + |
| 14 | +```clojure |
| 15 | +{:paths ["src"] |
| 16 | + :output-dir "lib" |
| 17 | + :extension "mjs"} |
| 18 | +``` |
| 19 | + |
| 20 | +Key implications: |
| 21 | +- `require` compiles to ES `import` — circular dependencies cause the same issues as in JS |
| 22 | +- Unrecognized symbols emit bare JavaScript calls — silent at compile time, crashes at runtime |
| 23 | +- This is the most common source of `ReferenceError: X is not defined` errors |
| 24 | +- Always check compilation output when a runtime error seems impossible from the source |
| 25 | + |
| 26 | +## REPL and Development Workflow |
| 27 | + |
| 28 | +Use `clojure_list_sessions` to find the Squint REPL session (typically `squint-repl`). Test pure functions and verify assumptions in the REPL before committing to files. |
| 29 | + |
| 30 | +Development cycle: |
| 31 | +1. Squint watch (`npx squint watch` or project-specific watcher) for continuous compilation |
| 32 | +2. REPL for incremental development of pure functions |
| 33 | +3. Compilation check for single files when needed |
| 34 | +4. Check watcher output after edits — zero-warnings baseline |
| 35 | + |
| 36 | +## Language Semantics |
| 37 | + |
| 38 | +### Keywords ARE Strings |
| 39 | + |
| 40 | +Squint compiles keywords to plain JavaScript strings: |
| 41 | + |
| 42 | +- `:foo` → `"foo"`, `:foo/bar` → `"foo/bar"` |
| 43 | +- `(= :loaded "loaded")` → `true` — they are the same value |
| 44 | +- `str` works naturally: `(str "prefix-" :status)` → `"prefix-status"` |
| 45 | +- `keyword?` does not exist — there is no distinct keyword type to test for |
| 46 | + |
| 47 | +### JS-Native Data Structures |
| 48 | + |
| 49 | +Maps are JS objects, vectors are JS arrays, sets are JS Sets. No persistent data structures: |
| 50 | + |
| 51 | +- `assoc`, `conj`, `update` return shallow copies — the original is not mutated (REPL-verified) |
| 52 | +- Nested objects are shared — deep mutations on nested values affect both original and copy |
| 53 | +- `(= a b)` on maps/vectors is reference equality, not structural |
| 54 | +- `assoc!` does NOT exist — use `assoc` |
| 55 | + |
| 56 | +### Async: `^:async` + `js-await` |
| 57 | + |
| 58 | +- Mark functions with `^:async` metadata — they return Promises |
| 59 | +- Both `js-await` and bare `await` work (REPL-verified). Convention: use `js-await` in Squint code for clarity, since bare `await` is the SCI convention. |
| 60 | +- No top-level `js-await` — must be inside an `^:async` function |
| 61 | +- `doseq` does NOT properly await `js-await` calls — iterations fire concurrently |
| 62 | +- Use `loop`/`recur` for sequential async iteration |
| 63 | + |
| 64 | +```clojure |
| 65 | +(defn ^:async process-items! [items] |
| 66 | + (loop [remaining items] |
| 67 | + (when (seq remaining) |
| 68 | + (js-await (handle-item! (first remaining))) |
| 69 | + (recur (rest remaining))))) |
| 70 | +``` |
| 71 | + |
| 72 | +### No `js->clj` / `clj->js` |
| 73 | + |
| 74 | +These functions do not exist. They compile to unqualified bare calls (`js__GT_clj()`) that crash at runtime with `ReferenceError`. Data is already JS-native — no conversion needed. |
| 75 | + |
| 76 | +### `nil` is `null` |
| 77 | + |
| 78 | +Squint compiles `nil` to JavaScript `null` (REPL-verified): |
| 79 | + |
| 80 | +- `nil?` returns `true` for both `null` and `undefined` (uses JS loose equality) |
| 81 | +- `identical?` distinguishes them: `(identical? nil js/undefined)` → `false` |
| 82 | +- APIs that return `undefined` test as `nil?` but are not `identical?` to `nil` |
| 83 | + |
| 84 | +## Function Availability |
| 85 | + |
| 86 | +Several `clojure.core` functions are missing or behave differently in Squint: |
| 87 | + |
| 88 | +| Function | Status | Workaround | |
| 89 | +|---|---|---| |
| 90 | +| `name` | does not exist | keywords are already strings — use directly | |
| 91 | +| `keyword` | does not exist | use the string directly | |
| 92 | +| `keyword?` | does not exist | no distinct keyword type | |
| 93 | +| `sequential?` | `true` for strings | use `vector?` to distinguish | |
| 94 | +| `js->clj` / `clj->js` | do not exist | data is already JS-native | |
| 95 | + |
| 96 | +Set callability: inline set literals work (`(#{:a :b} :a)` → `"a"`) but sets bound to vars are not callable (REPL-verified). Use `(contains? s :a)` for consistent behavior. |
| 97 | + |
| 98 | +No auto-resolved keywords — `::my-key` is a compiler error. Spell out the namespace. |
| 99 | + |
| 100 | +### Checking Whether a Function Exists |
| 101 | + |
| 102 | +When uncertain, query the Squint runtime directly: |
| 103 | + |
| 104 | +```bash |
| 105 | +node -e "import('squint-cljs/core.js').then(m => console.log(typeof m.someFn))" |
| 106 | +``` |
| 107 | + |
| 108 | +`undefined` means the function does not exist. The Squint source at `src/squint/core.js` in the [Squint repo](https://github.com/squint-cljs/squint) is the definitive reference for available core functions. |
| 109 | + |
| 110 | +When Squint does not recognize a symbol, it emits an unqualified JS call. The compiler does not error — but the generated code crashes at runtime. `refer` for missing functions silently succeeds but does not make them available. |
| 111 | + |
| 112 | +## Property Access and Interop |
| 113 | + |
| 114 | +- `(.-my-prop obj)` converts hyphens to underscores → `obj.my_prop` |
| 115 | +- Use `(aget obj "my-prop")` for literal property names with hyphens |
| 116 | +- `(:key obj)` works (compiles to string lookup on JS object) |
| 117 | +- Bare namespace requires fail — always use vector form: `(:require [lib :as alias])` |
| 118 | +- `js/` prefix works for global access: `js/document`, `js/console.log`, `js/fetch` |
| 119 | + |
| 120 | +## Idiomatic Style |
| 121 | + |
| 122 | +Prefer idiomatic Clojure functions over JavaScript interop when an equivalent exists. Squint supports most of `clojure.string` and the core library: |
| 123 | + |
| 124 | +```clojure |
| 125 | +;; Prefer |
| 126 | +(string/includes? s "needle") |
| 127 | +(string/replace s #"old" "new") |
| 128 | +(mapv transform items) |
| 129 | + |
| 130 | +;; Over |
| 131 | +(.includes s "needle") |
| 132 | +(.replace s "old" "new") |
| 133 | +(.map items transform) |
| 134 | +``` |
| 135 | + |
| 136 | +JS interop is appropriate for host-specific APIs (DOM, Node.js, browser APIs) where no Clojure equivalent exists. |
| 137 | + |
| 138 | +## Debugging Compiled Output |
| 139 | + |
| 140 | +When a runtime error does not match the source: |
| 141 | + |
| 142 | +1. Read the compiled `.mjs` file to see what Squint generated |
| 143 | +2. Search for unqualified function calls (e.g., `name(...)` instead of `squint_core.name(...)`) |
| 144 | +3. Trace `ReferenceError: X is not defined` back to missing core functions |
| 145 | +4. Check that the intended Clojure function is actually available in Squint's core.js |
| 146 | + |
| 147 | +## Invariants |
| 148 | + |
| 149 | +- `js-await` by convention in Squint code (distinguishes from SCI's `await`) |
| 150 | +- Never use `js->clj`/`clj->js` — data is already JS-native |
| 151 | +- Check compiled output on mysterious runtime errors — the compiler does not catch missing functions |
| 152 | +- `contains?` for set membership — do not call sets as functions from variables |
| 153 | +- Prefer Clojure functions over JS interop when both are available |
| 154 | +- Zero compilation warnings — address root causes |
0 commit comments