feat(core/formatter): add slice, sort, and merge array modifiers

[be-na17]

Adds three new modifiers for arrays

Slice modifier
Usage: ::slice(start, end) or ::slice(start)
Example: {stream.visualTags::slice(0, 2)}
Input: 10bit, HDR, DV, 3D, IMAX
Output: 10bit, HDR

Sort modifier
Usage: ::sort(asc) or ::sort(desc)
Example (alphabetical): {stream.audioTags::sort(asc)}
Input: Atmos, DTS-HD MA, TrueHD, OPUS, AAC
Output: AAC, Atmos, DTS-HD MA, OPUS, TrueHD
Example (numerical): {stream.seasons::sort(desc)}
Input: 1, 2, 3, 4, 5, 6, 7, 8
Output: 8, 7, 6, 5, 4, 3, 2, 1
Note: Combined alphabetical/numerical sorting is possible

Merge modifier
Usage: ::merge('{example.Array}')
Example: {stream.audioTags::merge('{stream.audioChannels}')}
Input: Atmos, TrueHD + 7.1
Output: Atmos, TrueHD, 7.1

Combined usage
Example: {stream.visualTags::merge('{stream.audioTags}')::merge('{stream.audioChannels}')::sort(asc)::slice(0, 4)::join(' - ')}
Input: HDR10, DV + Atmos, TrueHD + 7.1
Output: 7.1 - Atmos - DV - HDR10

Technical changes
Updated applySingleModifier: Added support for returning arrays, added parseValue parameter to support context access for merging.

Summary by CodeRabbit

• New Features

  • Added an array slice modifier for extracting subarrays with safe numeric bounds.
  • Added numeric-aware ascending and descending sort modifiers for mixed numeric/text values.
  • Improved modifier recognition to accept slice-style syntax and more flexible array/string transformations.

• Other

  • Modifier return types extended so modifiers can return arrays where applicable.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Extends the formatter modifier system in packages/core/src/formatters/base.ts: applySingleModifier now permits array returns; adds array slice(start[,end]) parsing and numeric-aware sort implementations (sort, rsort, lsort) via a shared getSortModifier; updates hardcoded/regex modifier matching to recognise slice syntax.

Changes

Cohort / File(s)	Summary
Formatter core & modifiers packages/core/src/formatters/base.ts	Updated applySingleModifier return type to include any[]; added slice(start[,end]) modifier with numeric parsing and safe slicing; introduced getSortModifier to provide numeric-aware sort/rsort and preserved lsort; updated arrayModifiers to use new sort/slice behavior; expanded hardcoded/regex modifier patterns to recognise slice variants.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• [Feature] Allow Multiple, Sequential Modifiers (to be applied to a variable) #368: Modifies modifier parsing/handling in packages/core/src/formatters/base.ts, including multi-modifier and hardcoded-regex matching changes that may overlap.
• feat: Add truncate(N) modifier to formatter #470: Adds parameterised modifier patterns (e.g., truncate) to the same hardcoded/regex modifier registry — likely touches the same matching scaffolding.
• Refactoring BaseFormatter for Readability & Ease of Changes #382: Adjusts applySingleModifier and the modifier registry in packages/core/src/formatters/base.ts, overlapping signature and modifier behaviour changes.

"I nibble code with careful paws,
Slicing arrays without a pause,
Sorting numbers, strings in line,
Modifiers hum — the format's fine,
A rabbit hops through tidy laws." 🐇

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main changes in the pull request, which adds slice and sort array modifiers to the core formatter.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/core/src/formatters/base.ts (1)

754-768: Slice modifier implementation is correct.

The logic correctly handles both slice(start) and slice(start, end) patterns with appropriate fallback behaviour.

Minor style inconsistency: Line 757 has _mod.length -1 whilst line 771 uses _mod.length - 1 with proper spacing around the operator.

Apply this diff for consistency:

-          const args = _mod
-            .substring(6, _mod.length -1)
-            .split(',')
-            .map((arg) => parseInt(arg.trim(), 10));
+          const args = _mod
+            .substring(6, _mod.length - 1)
+            .split(',')
+            .map((arg) => parseInt(arg.trim(), 10));

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 76bf4a2 and 6219029.

📒 Files selected for processing (1)

• packages/core/src/formatters/base.ts (5 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-09-14T16:46:18.507Z

Learnt from: DavidGracias
Repo: Viren070/AIOStreams PR: 375
File: packages/core/src/formatters/base.ts:0-0
Timestamp: 2025-09-14T16:46:18.507Z
Learning: In packages/core/src/formatters/base.ts, the modifier definitions intentionally include regex patterns (like "join('.*?')", "$.*?", "^.*?") that require pattern matching functionality. The buildModifierRegexPattern() method should not fully escape all regex metacharacters as this would break the intended regex matching behavior within modifier definitions.

Applied to files:

• packages/core/src/formatters/base.ts

🔇 Additional comments (6)

packages/core/src/formatters/base.ts (6)

592-594: LGTM! Context parameter properly propagated.

The addition of parseValue as a parameter enables context-aware modifiers like merge to access other variables from the parse context.

---

636-637: LGTM! Return type appropriately extended.

The extended return type any[] allows array modifiers to preserve array types through chaining, which is essential for the new slice, sort, and merge functionality.

---

769-791: LGTM! Robust sort implementation with numeric awareness.

The implementation correctly:

• Validates the direction parameter
• Uses spread operator to avoid mutation
• Provides numeric-aware sorting via localeCompare with numeric: true option
• Handles both pure numeric and mixed-type arrays appropriately

---

797-820: LGTM! Merge implementation with sensible fallback.

The implementation correctly:

• Validates the variable path format (requires {...} wrapper)
• Checks that the target property is an array before merging
• Gracefully falls back to the original array if the merge target is invalid

Note: The merge modifier doesn't support modifiers within the path (e.g., merge('{stream.audioChannels::slice(0, 2)}')), which is a reasonable design choice to maintain simplicity.

---

964-972: LGTM! Type signature appropriately broadened.

The updated signature any[] enables the sort modifier to handle arrays containing numbers, strings, or mixed types whilst maintaining numeric-aware comparison for consistency with the new parametrised sort modifier.

---

1025-1030: LGTM! Regex patterns correctly defined.

The hardcoded modifier patterns appropriately:

• Match both single-argument slice(n) and two-argument slice(n, m) forms with flexible whitespace
• Cover both ascending and descending sort directions
• Support both single and double quote delimiters for merge

[hugo9655]

These are very useful, hope this gets merged soon.

[Viren070]

hey @be-na17, sorry for the late response, but do you mind splitting the merge modifier into a separate PR?

The slice and sort are more simple and I can merge those but I would like to explore an alternative approach with the merge modifier where syntax could be something like {stream.audioTags::merge::stream.audioChannels}. I'm not sure how I feel with the current method and I'd need to test it myself.

[be-na17]

Hey, unfortunately I won't be in front of a computer for the foreseeable future.
Feel free to take this and implement (parts of) it in whichever way you like 😅

[Viren070]

Ah no worries. I'll do just that, thanks!

[Copilot]

Pull request overview

This PR adds new array manipulation modifiers (slice, sort, rsort, lsort, and reverse) to the formatter system, allowing users to extract subarrays, sort arrays in various ways, and reverse arrays before applying other transformations.

Changes:

• Added slice(start, end) modifier for extracting array subarrays with numeric indices
• Modified sort to use numeric-aware sorting and added rsort (reverse sort) and lsort (lexical sort) modifiers
• Changed array modifier return type from strings to arrays, allowing chaining of array operations

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.