@xcitedbs/client 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xcitedbs/client",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/unquery-ai-guide.md

@@ -85,6 +85,7 @@ A path selects a value from the current context.
 | `[n]` | Array index (0-based) | `"Dependants[0].FirstName"` |
 | `[expr]` | Computed index | `"Field1[$index+1]"` |
 | `[]` | Whole array (projection over all elements) | `"Array1[].Field1"` |
+| `[a:b]` | Array **slice** in a context modifier (half-open; negative counts from end) | `"scores:[0:3]"`, `"scores:[-2:]"` |
 | `/Field` | Absolute from document root | `"/employees.$(.)"` |
 | `../Field` | Up one path level (skips array indices) | `"../DBInstanceIdentifier"` |
 | `<<Field` | Read same field in *previous* document context | `"<<Field1"` after a `->$file(...)` |
@@ -259,18 +260,21 @@ Equivalent to SQL `GROUP BY bin`. Combine with aggregate values for grouped stat
 { "$(Title)": "$avg(Salary)" }
 ```
 
-### 5.4 Copy-all keys — `{}` and `{'regex'}`
+### 5.4 Copy-all keys — `{}`, `{'regex'}`, and slice `{a:b}`
 
-`{}` evaluates to *every* key in the queried object. `{'regex'}` evaluates to keys matching the regex.
+`{}` evaluates to *every* key in the queried object. `{'regex'}` evaluates to keys matching the regex. `{a:b}` is a positional **slice** of the source-key sequence (half-open, negative values count from the end) — keys are visited in their stored sort order, so this naturally gives "first K", "last K", or a middle range.
 
 ```json
 { "{}": "value" }                  // every key gets the constant 'value' (rarely useful)
 { "{}:": "." }                     // copy every key → its value (very useful)
 { "{'A.*B'}:": "." }               // copy only keys matching the regex
 { "{}:": ".?$key!='ID'" }          // copy all except ID (predicate filter)
+{ "{:3}:": "." }                   // first 3 keys (alphabetical)
+{ "{-2:}:": "." }                  // last 2 keys
+{ "{2:5}:": "." }                  // keys at positions 2..4 inclusive
 ```
 
-The trailing `:` after `{}` is a context modifier ("for each key, switch context to that key"). Without `:`, `{}` is just the empty-key spec.
+The trailing `:` after `{}` is a context modifier ("for each key, switch context to that key"). Without `:`, `{}` is just the empty-key spec. The slice form `{a:b}` mirrors the array slice `[a:b]` (see §4 path expressions and §6 context modifiers): `{:K}` is the first K, `{-K:}` the last K, `{a:b}` the half-open range.
 
 ### 5.5 Key utility functions
 
@@ -298,7 +302,9 @@ A modifier may be followed by `?cond` (predicate). Modifiers chain freely.
 | `:` (nothing after) | Repeat the key name as the path: `"Field1:"` ≡ `"Field1:Field1"` |
 | `:[]` | Iterate over each array element |
 | `:[n]` | Switch to array index `n` |
+| `:[a:b]` | Iterate over the array **slice** at indices `a..b` (half-open; negative counts from end) |
 | `:{}` | Iterate over each object field |
+| `:{a:b}` | Iterate over the object-key **slice** at positions `a..b` (half-open; negative counts from end) |
 | `:{'regex'}` | Iterate over fields matching regex |
 | `:**` | Recursive descent (every path under current) |
 | `:.` | Stay at current path (rarely needed) |
@@ -308,8 +314,18 @@ A modifier may be followed by `?cond` (predicate). Modifiers chain freely.
 { "result:Customers[]?Balance>100000:Accounts[]": ["accountNumber"] }
 { "result:{}": ["."] }
 { "#return:**": ["$key@unique_ascending"] }
+{ "first:scores[:3]": ["."] }              // first 3 elements of `scores`
+{ "tail:scores[-2:]": ["."] }              // last 2 elements
+{ "middle:scores[2:5]": ["."] }            // elements at positions 2..4
 ```
 
+**Slice semantics** (same shape for arrays and object-key iteration):
+- `[:K]` / `{:K}` — first K (start defaults to 0).
+- `[K:]` / `{K:}` — from index K to end.
+- `[a:b]` / `{a:b}` — half-open range `[a, b)`.
+- `[-K:]` / `{-K:}` — last K (negative values count from the end).
+- Out-of-range bounds are clamped; `b ≤ a` yields an empty result.
+
 ### 6.2 The `:Field` shorthand (very common)
 
 `"FirstName:"` is identical to `"FirstName:FirstName"`. Use it whenever the result key matches the source field:

package/unquery-grammar.md

@@ -151,7 +151,7 @@ Roughly in parse order:
 
 | Prefix / form | AST | Notes |
 |-----------------|-----|--------|
-| `[` optional `]` | `TExprSubfield(TExprField("."), expr?, is_index)` | `[]` = whole array on current `.`; `[e]` = index. |
+| `[` optional `]` | `TExprSubfield(TExprField("."), expr?, is_index)` | `[]` = whole array on current `.`; `[e]` = index. (Slice `[a:b]` form is currently parsed only on context modifiers, not in path expressions.) |
 | `$` `(` `expression` `)` | `TExprField(expr)` | Evaluate / path from dynamic name (`$()`). |
 | `$if` `(` `condition` `,` `expression` `,` `expression` `)` | `TExprITE` | |
 | `$call` `(` IDENT `)` | `TExprCall(name)` | Zero-arg user function by name. |
@@ -294,9 +294,12 @@ key ::= '$' '(' expression ')'              (* dynamic key → TQParamKey *)
      | '$' IDENT ... | '%' IDENT ...       (* whole thing parsed as expression() → TQParamKey *)
      | '{' '}'                             (* TQRegexKey empty regex *)
      | '{' QUOTED '}'                      (* TQRegexKey *)
+     | '{' slice '}'                       (* TQRegexKey + slice over source-key sequence *)
      | '#' directive
      | pathId                              (* TQSimpleKey, name may include quoted segments from pathId *)
 
+slice ::= INT? ':' INT?                    (* INT may be `-` INT for negative-from-end *)
+
 directive ::= 'if'
            | 'func' IDENT ( '(' IDENT ( ',' IDENT )* ')' )?   (* register arity; TQFuncDefinition *)
            | 'var' IDENT
@@ -336,8 +339,10 @@ Parsed **after** `key()` from the **same** JSON key string. Mode parameter `Cont
 | `->` … | `Arrow` | See §8.2 (`identifierExpression`, builtins, legacy JSON-field lookup, `->$each`); often `new_frame = true` |
 | `[` `]` | `Array` | traversal |
 | `[` INT `]` | *(string context)* | literal index path segment |
+| `[` (INT)? `:` (INT)? `]` | `Array` + slice | half-open slice; sets `array_slice_set` and the start/end fields on the `TQContextMod`. Negative ints count from end. (`-` token + INT recognized.) |
 | `.` | *(path)* | context string `"."` |
 | IDENT… `[` `]`? | `Array` if trailing `[]`, else path | Empty path + no `[` → **`Reskey`** mode |
+| IDENT… `[` slice `]` | `Array` + slice | `Field[a:b]` after a path |
 | Optional `?` `condition` after each atom | — | Wraps inner mod chain in `TQValueWithCond` |
 
 Recursion: `context_mod(...)` parses the **rest** of the chain; result wrapped in `TQContextMod` (expr or string form).