Partial CPS Development

Work with the partial-cps library, a lean Clojure/ClojureScript implementation of continuation-passing style transformations that provides lightweight coroutines and async/await functionality without scheduling framework overhead.

Project Overview

partial-cps transforms regular Clojure code into continuation-passing style at compile time using macros. It uses safe trampolining to avoid stack overflow while maintaining synchronous code sections for performance. The library is cross-platform, supporting both Clojure (JVM) and ClojureScript (JavaScript).

Key Architecture Components

1. **is.simm.partial-cps** - Public API entry point re-exporting key functions

2. **is.simm.partial-cps.ioc** - Inversion of Control implementation for CPS transformation via AST walking

3. **is.simm.partial-cps.runtime** - Runtime execution and trampolining for coroutines

4. **is.simm.partial-cps.async** - Async/await implementation built on the CPS transform

Development Workflow

When working on this project, follow these steps:

1. Build Operations

For building JARs:

```bash

clojure -T:build ci

```

For local installation:

```bash

clojure -T:build install

```

For deploying to Clojars:

```bash

clojure -T:build deploy

```

2. Testing Strategy

**Clojure Tests (JVM):**

```bash

clojure -M:test

```

**ClojureScript Tests (Node.js):**

One-time compilation and run:

```bash

npx shadow-cljs compile test && node target/test.js

```

Watch mode (requires two terminals):

```bash

Terminal 1: Compile with watch

npx shadow-cljs watch test

Terminal 2: Run tests

node target/test.js

```

**Testing Guidelines:**

3. REPL Development

**Clojure REPL with CIDER support:**

```bash

clojure -M:repl

```

**ClojureScript REPL (node-based):**

```bash

npx shadow-cljs cljs-repl test

```

4. Code Conventions

**Cross-platform Code:**

**Naming Conventions:**

**Code Organization:**

5. Understanding CPS Transformation

When modifying or debugging the CPS transform:

1. The `cps` macro accepts breakpoints and transforms code blocks

2. Breakpoints handle specific function calls (like `await`) during transformation

3. The IOC namespace walks the AST and inverts control flow at breakpoints

4. The runtime uses trampolining to avoid stack overflow

5. Async operations only hit the event loop when the effect handler schedules them

6. Common Development Tasks

**Adding a new breakpoint:**

1. Define the breakpoint handler in `ioc` namespace

2. Register it with the CPS transformation system

3. Add tests in both `.clj` and `.cljs` test files

4. Document the breakpoint in the public API if user-facing

**Debugging transformation issues:**

1. Use `macroexpand` to see the generated CPS code

2. Check the AST walking logic in `ioc` namespace

3. Verify trampolining behavior in `runtime` namespace

4. Test with both synchronous and asynchronous code paths

**Performance optimization:**

1. Minimize unnecessary trampolining for synchronous code

2. Avoid allocating closures in hot paths

3. Profile both JVM and JavaScript targets

4. Benchmark against core.async when appropriate

Important Constraints

Example Usage

When demonstrating or testing the library:

```clojure

(require '[is.simm.partial-cps :as cps])

(require '[is.simm.partial-cps.async :as async])

;; Basic CPS transformation

(cps/cps {}

(+ 1 2))

;; Async/await pattern

(async/go

(let [result (async/await (fetch-data))]

(process result)))

```