Motivation

Redis distinguishes between omitting the LIMIT clause and passing LIMIT 0 when trimming a stream with the approximate (~) strategy:

• No LIMIT clause — Redis applies an implicit effort cap of 100 * stream-node-max-entries examined entries per call.
• LIMIT 0 — the effort cap is disabled entirely; Redis trims as many macro nodes as the threshold requires in a single call.

(See the XADD / XTRIM docs: "Specifying the value 0 as count disables the limiting mechanism entirely.")

Today the library cannot express the second form. xTrim, xTrimMode, and XAdd all build the clause with:

if limit > 0 {
    args = append(args, "limit", limit)
}

so 0 is silently swallowed and there is no way to send XTRIM key MINID ~ <id> LIMIT 0 through the typed API. This matters in practice for periodic cleaners on busy streams: with the implicit default cap, a single XTRIM ... ~ call may not reclaim a large backlog, and the only workaround is dropping down to raw Do().

Changes

Introduces a documented negative-value sentinel, following the existing KeepTTL = -1 precedent in commands.go (the same "zero value already has a meaning, a third state is needed" problem for SET):

const XTrimLimitDisabled = -1

The limit parameter of XTrimMaxLenApprox, XTrimMinIDApprox, XTrimMaxLenApproxMode, XTrimMinIDApproxMode, and the XAddArgs.Limit field now have three documented states:

Implementation is a single shared helper, appendXTrimLimit, used by XAdd, xTrim, and xTrimMode, replacing the three duplicated if limit > 0 blocks.

Usage:

rdb.XTrimMinIDApprox(ctx, "stream", "1716000000000-0", redis.XTrimLimitDisabled)
// XTRIM stream MINID ~ 1716000000000-0 LIMIT 0

Backward compatibility

• No public API changes: all exported signatures and struct fields are unchanged.
• No behavior change for existing callers: limit = 0 still omits the clause; positive values are emitted as before. Only previously-meaningless negative values gain a meaning.
• Exact-trim commands (XTrimMaxLen, XTrimMinID, and their Mode variants) take no limit parameter and still can never emit LIMIT — Redis rejects LIMIT without ~ (ERR syntax error, LIMIT cannot be used without the special ~ option). For XAddArgs the library keeps its existing stance of not validating the Approx/Limit combination client-side (matching how the conflicting MaxLen/MinID pair is handled); this is now stated explicitly in the Limit field docs instead of being implicit.

Testing

Added server-less unit tests asserting the constructed command args via the existing captureCmdable pattern (stream_commands_unit_test.go):

• TestXTrim_LimitArgs — 13 cases covering omitted / positive / disabled limit across XTrimMaxLenApprox, XTrimMinIDApprox, their Mode variants, and pinning that exact-trim commands never emit LIMIT.
• TestXAdd_TrimLimitArgs — 5 cases covering the XAddArgs.Limit path, including clause ordering relative to the entry ID.

go build ./..., go vet ./..., and gofmt are clean; the pre-existing unit test suite passes.