Squint ClojureScript Dialect

In Squint, lazy sequences behave like ClojureScript. They are designed to satisfy three constraints:

1. Cached: Traversing the same sequence more than once computes each element only once.
2. Streaming: A single forward pass over a large or infinite sequence that is not retained runs in roughly constant memory.
3. Fast: Per-element overhead is low enough for high-performance pipelines.

Implementation-wise, the cache is a linked structure of cells. While a native JS iterator is single-shot, Squint's LazySeq uses a cursor that walks these cells. The first pass forces the cells and caches their contents; a second pass starts a fresh cursor at the head and reads the already-realized cached chunks without touching the underlying iterator.

When using Squint, object literals defined with #js/Map or standard JS object syntax can hold keywords as keys. However, when performing raw JavaScript interop (e.g., calling .get() on a native JS Map), you must be aware that the key type matters. A raw .get("a") call using a string will miss a key that was inserted as a keyword. The caller is responsible for ensuring the key type matches the one used during insertion.

// If a key is inserted as a keyword, raw JS string access will fail
// Example of the mismatch risk:
const m = #js/Map {:a 1};

// This works in Squint/CLJS context because it uses the keyword
m.get(:a); 

// This fails in raw JS interop because "a" is a string, not a keyword
// The caller owns the responsibility of using the correct key type
m.get("a"); 

In Squint, keywords are currently represented as plain strings. For example, the keyword :foo/bar is internally the string "foo/bar".

Implications for developers:

• (keyword? :foo) is not a meaningful check because keywords are strings.
• Keywords cannot be distinguished from strings in equality checks, sets, js/Map probes, or case dispatch. For example, (= :a "a") evaluates to true.
• Printing a keyword results in its string representation (e.g., :a prints as "a").

When implementing or using custom encoders for composite keys, the following invariants must hold to ensure value-semantic equality matches dequal behavior:

• Vector equality: encKey([1,2]) === encKey([1,2])
• LazySeq/List compatibility: encKey([1,2]) === encKey(gen 1,2) (vectors and lazy sequences with same elements are equal)
• Order sensitivity: encKey([1,2]) !== encKey([2,1]) (order matters for vectors)
• Type safety: encKey(['12']) !== encKey([1,2]) (prevents string/number collisions)
• Unordered key canonicalization: encKey({a,b}) === encKey({b,a}) (maps/sets must be sorted during encoding to ensure consistent keys)

When porting ClojureScript code to Squint, be aware of how certain data structures behave due to their mapping to JavaScript:

• Maps as Functions: In CLJS, maps can be used as functions (e.g., (next-player p)). In Squint, maps are plain JS objects, so you must use get instead (e.g., (get next-player p)).
• Sets: Squint sets compare by reference. If you are comparing a set of vectors (like [y x]) against a path, use = instead of the standard CLJS set equality logic.
• Vector Keys in Maps: Maps keyed by vectors (e.g., [y x]) are supported. Squint stringifies these keys consistently, ensuring that assoc-in and get-in operations round-trip correctly.

When :squint/dialect :cljs is active, the language semantics shift to match ClojureScript more closely:

• Keywords: Literals compile to globally interned Keyword objects. (= :a "a") is false. (str :foo) returns ":foo".
• Collections: Map, vector, and set literals compile to persistent data structures. To use native JS arrays or objects, use the #js escape hatch.
• Keyword Invocation: Supports (:foo m) and (:foo m nf) syntax.
• Equality: Since keywords are interned, === and case statements work correctly for keyword comparison.

Warning on Interop: In cljs mode, keywords never coerce to property names on JS objects. (get js-obj :foo) will return nil. To access a JS property using a keyword, you must explicitly convert it: (get js-obj (name :foo)) or use js->clj.

Squint uses JavaScript iteration protocols. Most functions like first, rest, map, and reduce call iterable on the collection before processing.

• seq: Returns an Iterable of the collection, or nil if empty.
• iterable: Returns an Iterable, even if empty.
• seqable?: Checks if a collection is iterable.

Note on Memory: Lazy seq function results hold onto their input. To allow garbage collection of large inputs, convert results to arrays when leaving scope.

(defn doit []
  (let [x [(-> (new Array 10000000)
               (.fill 0)) :foo :bar]
        ;; Big array `x` is still being held on to by `y`:
        y (rest x)]
    (println (js/process.memoryUsage))
    (vec y)))

Some core functions in Squint, such as min, max, and conj, are variadic and use the (...xs) rest parameter syntax. This causes a rest array to be allocated on every call, which can lead to performance regressions in hot loops (e.g., in VDOM patching).

To resolve this, the project is moving toward a compiler-level solution: emitting direct fixed-arity calls (similar to ClojureScript's .cljs$core$IFn$_invoke$arity$2 style). This avoids the overhead of rest array allocation for common arities. If you encounter performance issues with variadic functions in high-frequency loops, consider using the native JavaScript equivalent (e.g., js/Math.min) as a temporary workaround.

Squint vectors are mutable JS arrays, and cells cache their chunk arrays. To maintain sequence integrity, the following invariants must be respected:

1. No Aliasing: A cached chunk must never alias an array that the caller still holds. If a caller mutates that array, it would change the sequence after the fact.
2. Fresh Arrays: Chunk-aware operations must build a fresh output array per chunk; they must never mutate an input chunk.
3. concat Behavior: concat copies array collections into its chunks using slice instead of sharing them. This ensures mutating the input after concat is not observable on the resulting sequence.
4. The vec/doall Exception: vec and doall return the caller's array unchanged. This is a documented Squint behavior where the result aliases the input by design.