janet_skill

Overview

This skill guides writing idiomatic Janet code for new code, refactors, and code reviews. It emphasizes functional defaults, clear immutability, and pragmatic use of mutation for performance. It highlights Janet-specific idioms, common pitfalls, and real-world performance tradeoffs.

How this skill works

I inspect code and recommend patterns that favor expression-oriented, functional style using Janet primitives like map, filter, keep, and threading macros. When performance matters I suggest targeted imperative changes (var, @[], buffer) and show safe ways to limit mutation. I also flag Janet-specific gotchas: truthiness, equality, tuples vs arrays, nil punting, and macro hygiene.

When to use it

• Writing new Janet modules or functions and aiming for idiomatic style
• Refactoring code to be more functional, clearer, or safer
• Reviewing hot paths to decide between immutability and mutation
• Converting between tables, structs, arrays, and tuples correctly
• Designing parsers with PEG or using keep/partition/zipcoll idioms

Best practices

• Prefer pure functions, def bindings, and higher-order helpers by default
• Use var/@[]/buffer only when benchmarks justify mutation in hot paths
• Favor destructuring for clarity in parameters and let bindings
• Use keep, mapcat, partition, and threading macros to build readable pipelines
• Be explicit about emptiness, equality (deep= vs =) and sentinel values for nil

Example use cases

• Refactor a loop-based aggregator into a clear reduce pipeline or a fast mutable builder when data is large
• Review a parser using PEG and recommend keep/partition or mapcat patterns for sequence processing
• Convert mutable table building into an immutable API by building mutable then freezing with table/to-struct
• Optimize string-heavy reporting by switching from repeated concatenation to buffer/push-string
• Fix bugs caused by confusion between tuples and arrays or by nil disappearing from tables