Higher-Level Command API for the Pony Redis Client

[SeanTAllen]

The current API exposes raw RESP protocol semantics: callers build commands as Array[ByteSeq] val and receive RespValue responses that must be pattern-matched. This is the right foundation, but most Redis clients layer a typed command API on top. This document explores what that layer should look like in Pony.

What Other Clients Do

Five popular Redis clients were studied: go-redis (Go), redis-py (Python), ioredis (Node.js), redis-rs (Rust), and Jedis (Java). They converge on a common structure with language-specific variations.

Common Patterns

Named methods for commands. Every client provides get(key), set(key, value), incr(key), etc. instead of requiring callers to assemble raw command arrays. This is the single most universal feature.

Typed responses. Rather than returning a generic "response" union, each command method communicates the expected return type. The mechanism varies:

• go-redis: Returns typed command objects (*StringCmd, *IntCmd, *BoolCmd) with .Result() methods
• redis-rs: Generic return type parameter (RV: FromRedisValue) — the caller specifies what type they want via annotation
• Jedis: Concrete return types per method (String, long, boolean)
• redis-py / ioredis: Dynamic typing / TypeScript overloads

Command grouping. Commands are organized by Redis data type (strings, hashes, lists, sets, sorted sets, etc.), though the mechanism varies from traits/interfaces to mixin classes to auto-generated code.

Pipeline reuse. Pipeline objects expose the same command methods as the client itself, so callers don't learn a different API for pipelined operations.

Polymorphic commands are split. When a command can return different types depending on arguments (e.g., SET with NX returns nil-or-OK, SET with GET returns the old value), clients split them into separate methods: set(), set_nx(), set_get().

Design Decisions for Pony

Decision 1: Where does the higher-level API live?

Options:

• (A) Methods on Session. Add get(), set(), etc. directly to the Session actor.
• (B) A separate Commands trait/interface. Define a trait with command methods, implemented by Session. (This is what redis-rs and Jedis do.)
• (C) A wrapper actor or class. A Client actor that wraps Session and adds typed commands.
• (D) Free-standing functions / primitives. Command builder functions that return Array[ByteSeq] val and/or response parser functions. No new actor, just helpers.

Analysis:

Option A is the simplest but makes Session large and mixes protocol-level concerns with command-level convenience. Option B is conceptually clean but Pony traits require all implementors to provide all methods — a large command trait is unwieldy and ties the protocol layer to the convenience layer. Option C adds an unnecessary indirection layer between the user and the session. Option D keeps Session focused on connection management and lets the higher-level API be purely additive — but it doesn't solve the response typing problem, since execute() still returns raw RespValue.

Recommendation: Option A — methods on Session. Session is already the API entry point. The command methods are thin wrappers around execute() with typed callbacks. Keeping them on Session means users have one object to work with. The alternative that looks cleanest architecturally (D) doesn't actually solve the main user pain point (response handling), and B/C add complexity without proportional benefit.

File size concern: Adding ~35 behaviors to Session will grow session.pony significantly (currently ~760 lines). In Pony, behaviors must be defined within the actor definition or via trait composition — you can't add behaviors from separate files. The practical approach is trait composition: define traits like _StringCommands, _HashCommands, etc. in separate files, each providing command behaviors that delegate to an execute() method. Session composes them. This is similar to redis-py's mixin approach and keeps each file focused. Note that this is Option B used as an internal organization mechanism, not as a public API — users still see one Session actor with all methods.

Decision 2: How should typed responses be delivered?

This is the central design question. Pony is actor-based, so all responses are asynchronous — there are no blocking .Result() calls or await expressions.

Options:

• (A) Typed callback interfaces. Define StringResultReceiver, IntResultReceiver, BoolResultReceiver, etc., each with a typed redis_string_result(session, key, (String | None)) behavior. Each command method takes the appropriate receiver type.
• (B) A single callback with a typed result union. Define a CommandResult union type like (StringResult | IntResult | BoolResult | ErrorResult) and deliver it through a single callback method.
• (C) Lambda/closure callbacks. Each command method takes a lambda: get(key, {(result: (String | None)) => ... }).
• (D) Keep ResultReceiver but add response extraction helpers. Don't change the callback model; instead provide helper primitives/functions to extract typed values from RespValue.

Analysis:

Option A is the most type-safe but creates an explosion of receiver interfaces. A caller implementing StringResultReceiver and IntResultReceiver would get both redis_string_result and redis_int_result callbacks with no way to know which command they correspond to (same FIFO tracking problem as today). Option B has the same correlation problem and creates a new union type that doesn't add much over RespValue. Option C is attractive but has a fundamental limitation: a lambda that captures mutable (ref) state from the enclosing actor cannot be sent across actor boundaries. In practice, response handlers almost always need to update actor state (track step counters, store results, trigger follow-up commands), so the lambda would need ref captures and couldn't be passed to another actor. Wrapping each lambda in a forwarding actor would work but adds hidden overhead and indirection. Option D is the most pragmatic: it doesn't change the async model but removes the boilerplate.

However, there's a hybrid approach worth considering:

(E) Command methods accept ResultReceiver but the response is pre-validated. The command methods are thin wrappers that call execute() with the same ResultReceiver. The value-add is on the command construction side (typed arguments, no raw arrays) and on the response extraction side (helper functions/methods on RespValue). The callback model stays the same.

The key insight is that in an actor-based system, the command construction pain and the response extraction pain are the two separate problems. We can solve them independently:

• Command construction: Named methods with typed arguments → no more Array[ByteSeq] val
• Response extraction: Helper methods/functions → less boilerplate in match expressions

We don't need to change the callback model to get most of the value.

Recommendation: Option E. Named command methods for construction, helper methods for response extraction, same ResultReceiver callback model. This is additive — nothing breaks, and users can mix raw execute() calls with typed methods freely. It also means we don't need to solve the response correlation problem (which command does this response belong to?) at the library level — that remains the caller's responsibility, same as today.

Decision 3: What response extraction helpers should look like

Given Decision 2's recommendation, we need helpers to reduce RespValue match boilerplate.

Options:

• (A) Methods on RespValue. Add as_string(), as_integer(), as_bool(), etc. to the RespValue type. But RespValue is a type alias (union), not a class — you can't add methods to it in Pony.
• (B) A primitive with functions. RespConvert.as_string(value): (String | None), RespConvert.as_integer(value): (I64 | None), etc.
• (C) Methods on each RespValue member. This doesn't help — the caller still needs to match first.
• (D) A single RespExtract primitive with partial functions. Each function is partial (returns the value or errors), suitable for use in try blocks.

Analysis:

Option B is the most natural fit. A RespConvert (or similar) primitive with functions that do the "match and extract" pattern the caller would otherwise write. The functions handle cross-type coercions that are sensible: as_string() could accept both RespSimpleString and RespBulkString, converting the bulk string's Array[U8] val to String. as_integer() extracts from RespInteger. For nil, as_string() returns None.

Option D (partial functions) is slightly more ergonomic: let s = RespConvert.as_string(response)? in a try block. But None return values compose better in Pony — the caller can use match or as without try/else blocks.

Recommendation: Option B — a primitive with total functions that distinguish between "Redis returned null" and "wrong extraction function." The return type is (T | RespNull | None) where RespNull means the key doesn't exist (expected) and None means the RESP type didn't match the extraction function (a programming error or unexpected server response). This respects the "distinct semantics deserve distinct representations" principle — these two cases have different meanings and different appropriate caller responses.

Proposed API sketch:

primitive RespConvert
  fun as_string(value: RespValue): (String | RespNull | None) =>
    """
    Extract a string from a RespSimpleString, RespBulkString, or
    RespVerbatimString. For RespVerbatimString, only the data is
    returned — the encoding hint is discarded. Use a direct match
    on RespVerbatimString when the encoding matters.
    Returns RespNull when Redis returned null. Returns None when
    the value is a non-string RESP type.
    """
    match value
    | let s: RespSimpleString => s.value
    | let b: RespBulkString => String.from_array(b.value)
    | let v: RespVerbatimString => String.from_array(v.value)
    | RespNull => RespNull
    else
      None
    end

  fun as_bytes(value: RespValue): (Array[U8] val | RespNull | None) =>
    """
    Extract raw bytes from a RespBulkString or RespVerbatimString.
    For RespVerbatimString, only the data bytes are returned — the
    encoding hint (e.g., "txt", "mkd") is discarded. Use a direct
    match on RespVerbatimString when the encoding matters.
    Returns RespNull when Redis returned null. Returns None when
    the value is a non-bytes RESP type.
    """
    match value
    | let b: RespBulkString => b.value
    | let v: RespVerbatimString => v.value
    | RespNull => RespNull
    else
      None
    end

  fun as_integer(value: RespValue): (I64 | RespNull | None) =>
    """
    Extract an integer from a RespInteger. Returns RespNull when
    Redis returned null. Returns None for non-integer types.
    """
    match value
    | let i: RespInteger => i.value
    | RespNull => RespNull
    else
      None
    end

  fun as_bool(value: RespValue): (Bool | RespNull | None) =>
    """
    Extract a boolean from a RespBoolean. Returns RespNull when
    Redis returned null. Returns None for non-boolean types.
    """
    match value
    | let b: RespBoolean => b.value
    | RespNull => RespNull
    else
      None
    end

  fun as_array(value: RespValue): (Array[RespValue] val | RespNull | None) =>
    """
    Extract an array from a RespArray. Returns RespNull when
    Redis returned null. Returns None for non-array types.
    """
    match value
    | let a: RespArray => a.values
    | RespNull => RespNull
    else
      None
    end

  fun as_double(value: RespValue): (F64 | RespNull | None) =>
    """
    Extract a floating-point number from a RespDouble. Returns RespNull
    when Redis returned null. Returns None for non-double types.
    """
    match value
    | let d: RespDouble => d.value
    | RespNull => RespNull
    else
      None
    end

  fun as_big_number(value: RespValue): (String | RespNull | None) =>
    """
    Extract an arbitrary-precision integer from a RespBigNumber as a
    string (the value may exceed I64 range). Returns RespNull when
    Redis returned null. Returns None for non-big-number types.
    """
    match value
    | let b: RespBigNumber => b.value
    | RespNull => RespNull
    else
      None
    end

  fun as_map(value: RespValue):
    (Array[(RespValue, RespValue)] val | RespNull | None)
  =>
    """
    Extract key-value pairs from a RespMap. Returns RespNull when
    Redis returned null. Returns None for non-map types.
    """
    match value
    | let m: RespMap => m.pairs
    | RespNull => RespNull
    else
      None
    end

  fun as_set(value: RespValue): (Array[RespValue] val | RespNull | None) =>
    """
    Extract elements from a RespSet. Returns RespNull when Redis
    returned null. Returns None for non-set types.
    """
    match value
    | let s: RespSet => s.values
    | RespNull => RespNull
    else
      None
    end

  fun as_error(value: RespValue): (String | None) =>
    """
    If the value is a RespError or RespBulkError, return its message.
    Otherwise None.
    """
    match value
    | let e: RespError => e.message
    | let e: RespBulkError => String.from_array(e.message)
    else
      None
    end

  fun is_ok(value: RespValue): Bool =>
    """
    True if the value is a RespSimpleString with value "OK".
    """
    match value
    | let s: RespSimpleString => s.value == "OK"
    else
      false
    end

Note: there is no as_push helper for RespPush. Push messages are routed separately by _ResponseHandler and delivered to SubscriptionNotify callbacks — they never reach ResultReceiver, so RespConvert (which operates on ResultReceiver responses) does not need to handle them.

Decision 4: Command method signatures

Options:

• (A) Mirror Redis command syntax exactly. set(key: String, value: String, receiver: ResultReceiver) for the basic case, with separate methods for variants: set_nx(key, value, receiver), set_ex(key, value, ttl, receiver), etc.
• (B) Use option objects. set(key, value, receiver) for the basic case, set_options(key, value, opts: SetOptions, receiver) for the full matrix. (redis-rs pattern.)
• (C) All optional arguments on one method. set(key, value, receiver where nx = false, xx = false, ex = None, px = None) using Pony's named/default arguments.
• (D) Minimal — only the most common forms. set(key, value, receiver), get(key, receiver), del(keys, receiver). Don't try to cover every Redis option. Users fall back to execute() for advanced forms.

Analysis:

Option A (go-redis/Jedis pattern) is the most explicit and works well for the common forms, but the number of SET variants alone (NX, XX, EX, PX, EXAT, PXAT, KEEPTTL, GET, IFEQ, IFGT...) creates an explosion. Option B is cleaner for complex commands but adds a builder class per command. Option C becomes unwieldy — SET has 10+ options. Option D is the most practical for a first iteration: cover the 80% case, let execute() handle the rest.

A hybrid of A and D makes the most sense: provide the most common forms as named methods, don't try to cover every option combination. Users who need SET key value NX EX 60 GET can use execute(). This follows the "it is easier to give than take away" principle — start minimal, expand based on need.

Recommendation: Hybrid A+D. Common forms get named methods. Uncommon option combinations use execute().

Decision 5: Which commands to include in the first iteration

Starting minimal and expanding is better than trying to cover all ~400 Redis commands. The priority should be commands that:

1. Are used frequently
2. Benefit most from typed wrappers (non-trivial response handling)
3. Are awkward with raw execute() (multi-argument construction)

Proposed initial command set:

String commands:

• get(key, receiver) — response: bulk string or null
• set(key, value, receiver) — response: OK
• set_nx(key, value, receiver) — maps to SET key value NX; response: OK or null
• set_ex(key, value, seconds, receiver) — response: OK
• incr(key, receiver) — response: integer
• decr(key, receiver) — response: integer
• incr_by(key, amount, receiver) — response: integer
• decr_by(key, amount, receiver) — response: integer
• mget(keys, receiver) — response: array of bulk strings/nulls
• mset(pairs, receiver) — response: OK

Key commands:

• del(keys, receiver) — response: integer (count)
• exists(keys, receiver) — response: integer (count)
• expire(key, seconds, receiver) — response: integer (0 or 1)
• ttl(key, receiver) — response: integer (seconds or -1/-2)
• persist(key, receiver) — response: integer (0 or 1)
• keys(pattern, receiver) — response: array
• rename(key, new_key, receiver) — response: OK
• type_of(key, receiver) — response: simple string (type is a reserved keyword)

Hash commands:

• hget(key, field, receiver) — response: bulk string or null
• hset(key, field, value, receiver) — response: integer (0 or 1)
• hdel(key, fields, receiver) — response: integer (count)
• hget_all(key, receiver) — response: array of alternating field/value (RESP2) or map (RESP3)
• hexists(key, field, receiver) — response: integer (0 or 1)

List commands:

• lpush(key, values, receiver) — response: integer (length)
• rpush(key, values, receiver) — response: integer (length)
• lpop(key, receiver) — response: bulk string or null
• rpop(key, receiver) — response: bulk string or null
• llen(key, receiver) — response: integer
• lrange(key, start, stop, receiver) — response: array

Set commands:

• sadd(key, members, receiver) — response: integer (count added)
• srem(key, members, receiver) — response: integer (count removed)
• smembers(key, receiver) — response: array (RESP2) or set (RESP3)
• sismember(key, member, receiver) — response: integer (0 or 1)
• scard(key, receiver) — response: integer

Server commands:

• ping(receiver) — response: PONG
• echo(message, receiver) — response: bulk string
• dbsize(receiver) — response: integer
• flushdb(receiver) — response: OK

This is roughly 35-40 commands — enough to be useful without trying to boil the ocean. The full Redis command set has ~400+ commands; covering them all is a long-tail effort.

Decision 6: Argument types

Options:

• (A) String for everything. set(key: String, value: String, receiver) — simple, but loses binary safety.
• (B) ByteSeq for values. set(key: String, value: ByteSeq, receiver) — keys are strings, values can be binary.
• (C) Array[U8] val for values. More explicit about binary data. Callers pass "hello".array() for string values.
• (D) String for both, with separate binary variants. set(key, value, receiver) and set_binary(key, binary_value, receiver).

Analysis:

Redis keys are almost always strings. Redis values can be binary but are usually strings. Making the common case easy (String) while allowing the uncommon case (binary) is the goal. Option B (ByteSeq) lets callers pass either String or Array[U8] val — but ByteSeq in Pony is (String val | Array[U8 val] val), which means the command builder would need to handle both. Actually, since we're building Array[ByteSeq] val for execute(), and both String and Array[U8] val satisfy ByteSeq, option A (all Strings) is simplest for the common case, and users who need binary values can use execute() directly.

Recommendation: Option A — String arguments for keys and values. This covers 95%+ of usage. Binary-value users already have execute(). We can add binary variants later if demand warrants it.

Decision 7: Command naming conventions

Most Redis commands map directly to lowercase Pony method names. A few need special handling:

• TYPE → type_of (Pony keyword conflict — type is reserved)
• HGETALL → hget_all (snake_case at word boundaries)
• LPUSH → lpush (lowercase, already valid)
• SISMEMBER → sismember (lowercase, already valid)
• KEYS → keys (not a Pony keyword — usable directly)
• ECHO → echo (not a Pony keyword — usable directly)

Recommendation: Use lowercase snake_case versions of Redis command names. The only keyword conflict in the initial command set is TYPE → type_of. Multi-word compound commands use underscores at word boundaries: hget_all, set_nx, set_ex, incr_by.

Decision 8: Pipeline API considerations

Currently pipelining is implicit — every execute() call sends immediately. The typed command methods would work the same way since they delegate to execute(). This means the pipeline API gets the typed methods "for free."

The question is whether we should also add an explicit pipeline abstraction (buffer commands, send as batch, correlate responses). This is what go-redis's Pipeline(), redis-py's pipeline(), etc. provide.

Recommendation: Defer explicit pipeline abstraction. The current implicit pipelining model works and is consistent with how Pony actors naturally behave. An explicit pipeline with response correlation is a significant design effort (especially in an actor-based system where responses arrive asynchronously) and should be its own focused project.

Summary of Recommendations

1. API location: Methods on Session actor, organized internally via trait composition (_StringCommands, _HashCommands, etc.)
2. Response model: Keep ResultReceiver, add RespConvert extraction helpers
3. Response extraction: RespConvert primitive with total functions returning (T | RespNull | None) — distinguishing "Redis null" from "wrong extraction type"
4. Command signatures: Common forms only, execute() for advanced options
5. Initial scope: ~35 commands across strings, keys, hashes, lists, sets, server
6. Argument types: String for keys and values (binary via execute())
7. Naming: Snake_case Redis names; only type needs renaming (type_of)
8. Pipelining: Defer explicit pipeline abstraction; implicit pipelining works via typed methods

Example: Before and After

Before (current API)

// Setting a key
let cmd: Array[ByteSeq] val = ["SET"; "user:1"; "Alice"]
session.execute(cmd, this)

// In the response handler
be redis_response(session: Session, response: RespValue) =>
  match response
  | let s: RespSimpleString =>
    if s.value == "OK" then
      // Success — now get it back
      let cmd: Array[ByteSeq] val = ["GET"; "user:1"]
      session.execute(cmd, this)
    end
  | let b: RespBulkString =>
    let name = String.from_array(b.value)
    _out.print("Name: " + name)
  | let e: RespError =>
    _out.print("Error: " + e.message)
  end

After (with higher-level API)

// Setting a key
session.set("user:1", "Alice", this)

// In the response handler — still needs step tracking for pipelined commands
be redis_response(session: Session, response: RespValue) =>
  _step = _step + 1
  if _step == 1 then
    // SET response
    if RespConvert.is_ok(response) then
      session.get("user:1", this)
    end
  elseif _step == 2 then
    // GET response
    match RespConvert.as_string(response)
    | let name: String =>
      _out.print("Name: " + name)
    | RespNull =>
      _out.print("Key not found")
    end
  end

The command construction becomes one-liners. The response handling is still explicit — callers still track which command each response corresponds to (the step counter pattern). The improvement is twofold: no raw Array[ByteSeq] val construction, and RespConvert eliminates nested pattern matching on RESP types. The callback model and FIFO correlation are unchanged.

Intentional Omissions

• Sorted set commands (ZADD, ZRANGE, ZRANK, etc.) are omitted from the initial command set. They are commonly used but have complex argument patterns (scores, ranges with BYSCORE/BYLEX/REV, LIMIT). Adding them later is straightforward; getting the initial API shape right is more important.

• Stream commands (XADD, XREAD, XREADGROUP, etc.) are omitted. They have the most complex argument patterns of any Redis command family and would benefit from dedicated design work.

Open Questions for Discussion

1. Should we provide typed receiver interfaces for common patterns? For example, a StringReceiver interface with redis_string(session, (String | RespNull)) and redis_error(session, String) that wraps the pattern matching internally. This would be opt-in alongside ResultReceiver, not a replacement. The downside is interface proliferation.

2. How should RESP2/RESP3 differences be handled? Some commands return different types depending on protocol version. The most prominent example is HGETALL: it returns a flat RespArray of alternating keys and values in RESP2, but a RespMap in RESP3. Without normalization, an hget_all convenience method provides limited value — callers still need to match both types. Three options:

   • (a) Don't normalize — document the difference and let callers handle it. Simple but reduces the value of the convenience method.
   • (b) Normalize in RespConvert — add an as_string_map helper that handles both RespMap and alternating-element RespArray formats. This pushes the complexity into the library.
   • (c) Normalize in the command method — have hget_all internally convert the response before passing to the receiver. This would require a wrapper around ResultReceiver, adding complexity.
     Option (b) seems most natural — it's consistent with RespConvert handling cross-type extraction (like as_string accepting both RespSimpleString and RespBulkString).

3. Should there be a "fire and forget" variant? Some callers don't care about the response (e.g., SET in a write-heavy loop). A set_noreply(key, value) that uses a no-op receiver internally would reduce boilerplate. But this hides errors, which conflicts with explicit error handling principles.

[SeanTAllen]

Decision 1: Option D — Free-standing functions/primitives

After discussion, we're going with Option D instead of the recommended Option A.

The key insight

The analysis claimed D "doesn't solve the response typing problem, since execute() still returns raw RespValue." But Option A doesn't solve it either — the command methods still take ResultReceiver and responses come back as RespValue through redis_response. Response extraction is handled entirely by RespConvert (Decision 3), which is a standalone primitive that works identically regardless of where the command was constructed. Both options have the exact same response story.

The only actual difference between A and D is call-site ergonomics on the command construction side:

// Option A
session.set("user:1", "Alice", this)

// Option D
session.execute(RedisString.set("user:1", "Alice"), this)

That's a modest difference, and D has concrete advantages that outweigh it.

Why D is the better fit

• Explicit over implicit. The two-step nature is visible — you're building a command, then executing it. No hidden delegation chain.
• Separation of concerns. Command construction (what bytes go on the wire) is a pure function. Session (connection management, state machine, pub/sub routing) is orchestration. These are genuinely separate concerns and D keeps them separate.
• It is easier to give than take away. Starting with D is non-committal. If call-site ergonomics become a real pain point, wrapping them as Session methods later is trivial and additive. Going the other direction (removing methods from Session) would be a breaking change.
• Testability. Command builders are pure functions from arguments to Array[ByteSeq] val. They can be tested directly without any actor machinery — just assert on the output array.
• Session stays focused. No trait composition machinery needed on Session. No growing Session's public API surface. New command groups can be added, reorganized, or removed without touching the protocol layer.

Implications for other decisions

• Decision 2 (response model): Unchanged — RespConvert is independent of command construction.
• Decision 3 (response extraction): Unchanged.
• Decision 4 (command signatures): Still applies. The signatures live on primitives instead of Session behaviors, but the design questions (which forms to provide, how to handle variants) are the same.
• Decision 7 (naming): Still applies for method names. Additionally needs a naming convention for the primitives themselves (e.g., RedisString, RedisHash, RedisList, etc.).
• Decision 8 (pipeline): Even more naturally compatible — command builders just produce arrays that get passed to execute(), so pipelining works exactly as before with no additional consideration.

Updated example

// Setting a key
session.execute(RedisString.set("user:1", "Alice"), this)

// In the response handler
be redis_response(session: Session, response: RespValue) =>
  _step = _step + 1
  if _step == 1 then
    if RespConvert.is_ok(response) then
      session.execute(RedisString.get("user:1"), this)
    end
  elseif _step == 2 then
    match RespConvert.as_string(response)
    | let name: String =>
      _out.print("Name: " + name)
    | RespNull =>
      _out.print("Key not found")
    end
  end

[SeanTAllen]

Decision 6: Option B — ByteSeq for keys and values

Going with ByteSeq for both keys and values instead of the recommended Option A (String for everything).

Reasoning

ByteSeq is the standard Pony idiom for data going over the wire. TCPConnection.write() takes ByteSeq, and Pony programmers expect network-facing APIs to follow the same pattern. Using String would feel non-idiomatic.

There's no cost to this choice:

• Callers passing String don't notice the difference — String satisfies ByteSeq.
• The command builders produce Array[ByteSeq] val for execute(), so ByteSeq arguments drop straight into the array with no extra handling.
• The RESP serializer writes both String and Array[U8] val identically — a bulk string with a length prefix followed by the raw bytes. The wire format is the same regardless of which variant the caller passes.

There's no reason to distinguish keys from values here. Redis treats both as binary-safe byte sequences, and by the time they reach the network they're all just bytes. Restricting keys to String would be an artificial constraint with no benefit.

Updated example signature

primitive RedisString
  fun set(key: ByteSeq, value: ByteSeq): Array[ByteSeq] val =>
    ["SET"; key; value]

  fun get(key: ByteSeq): Array[ByteSeq] val =>
    ["GET"; key]

[SeanTAllen]

Review of remaining decisions after D1 (Option D) and D6 (ByteSeq)

Decision 2: Dissolved

With Decision 1 choosing Option D (free-standing functions), the question of "how should typed responses be delivered" is trivially answered — command builders are pure functions returning Array[ByteSeq] val and never touch ResultReceiver or responses. The response side stays as-is: ResultReceiver for delivery, RespConvert for extraction. There's no decision left to make; it falls out automatically from Decision 1.

Decision 3: Unchanged

RespConvert is completely independent of where commands are built. The recommendation (primitive with total functions returning (T | RespNull | None)) still holds.

Decision 4: Unchanged

The design questions (which forms to provide, how to handle variants) are the same whether signatures live on Session behaviors or primitive functions. Slightly simpler with D since they're pure functions with no async considerations.

Decision 5: Unchanged

No dependency on D1 or D6.

Decision 7: Extended — primitive naming

Method naming conventions (snake_case, type_of for TYPE, underscores at word boundaries) are unchanged. The primitives themselves follow the pattern Redis + Redis data type name:

• RedisString — string commands (GET, SET, INCR, etc.)
• RedisKey — key commands (DEL, EXISTS, EXPIRE, etc.)
• RedisHash — hash commands (HGET, HSET, HDEL, etc.)
• RedisList — list commands (LPUSH, RPUSH, LPOP, etc.)
• RedisSet — set commands (SADD, SREM, SMEMBERS, etc.)
• RedisServer — server commands (PING, ECHO, DBSIZE, etc.)

Decision 8: Unchanged

Even more straightforward with D — command builders produce arrays, execute() sends them, implicit pipelining works as before.

Open Question 1 (typed receiver interfaces): Deferred

With D, typed receivers would be adapter actors that implement ResultReceiver, internally call RespConvert, and forward to a typed interface. This can be added later if RespConvert proves insufficient for common patterns. Start without them.

Open Question 2 (RESP2/RESP3 differences): Resolved — Option (a)

Don't normalize. Document the difference and let callers handle it.

Adding normalization (e.g., an as_string_map helper that handles both RespMap and alternating-element RespArray) is adding API surface. If the normalization turns out to be wrong — lossy conversion, unexpected edge cases, a target type that doesn't quite fit — removing or changing it is a breaking change. This contradicts the "it is easier to give than take away" principle.

Option (a) is the conservative choice. Users handle the RESP2/RESP3 difference themselves with direct pattern matching. If normalization turns out to be a real pain point, we add it later — informed by actual usage rather than speculation.

Open Question 3 (fire and forget): Resolved — user-side pattern

No library support needed. Users who want to discard responses create a no-op ResultReceiver actor and reuse it:

actor DiscardResult is ResultReceiver
  be redis_response(session: Session, response: RespValue) => None
  be redis_command_failed(session: Session,
    command: Array[ByteSeq] val, failure: ClientError) => None

Usage: session.execute(RedisString.set(key, value), DiscardResult). One reusable actor, works with every command. This is a pattern, not a library feature.

[SeanTAllen]

Ergonomic awkwardness with RespConvert

PR #17 implemented the command builders and RespConvert as designed. In practice, the response handling pattern for commands that return OK-or-error (like SET) feels awkward:

be redis_response(session: Session, response: RespValue) =>
  if RespConvert.is_ok(response) then
    _out.print("Response: OK")
  else
    match RespConvert.as_error(response)
    | let msg: String => _out.print("Error: " + msg)
    end
  end

The if check for OK and the match for errors are two different control flow styles that don't compose well. For a SET response there are only two possibilities (OK or error), but the code reads as two separate checks rather than one exhaustive match. This gets worse with SET NX which adds a third case (RespNull).

More research is needed into what a cleaner API shape would look like for this common pattern.