@arkiv-network/sdk 0.8.1-dev.1 → 0.9.0-next.2

package/src/query/errors.ts

@@ -1,18 +1,17 @@
-import type { TypeTag } from "../attr"
+import type { TypeTag } from "../schema"
 
 /**
  * A predicate asked for an operator the query language does not define for that type.
  *
- * The operator × type matrix is part of the language, not a policy: a range comparison on an
- * equality-only type is a **parse error** at the node, not an empty result. Catching it here turns
- * a round trip and an RPC error code into a stack trace pointing at the call site.
+ * The operator × type matrix is part of the language, not a policy: a prefix test on a type other
+ * than `str` is a **type error** at the node (a {@link QueryError} of kind `"type"`), not
+ * an empty result. Catching it here turns a round trip and an RPC error code into a stack trace
+ * pointing at the call site.
  *
- * | | `=` `!=` | `<` `<=` `>` `>=` | `STARTSWITH` |
- * | --- | --- | --- | --- |
- * | `bool` | yes | no | no |
- * | `i32` `u64` `u256` `dec` | yes | yes | no |
- * | `str` | yes | no | yes |
- * | `addr` `key` `bytes32` | yes | no | no |
+ * | | `=` `!=` `<` `<=` `>` `>=` `BETWEEN` | `STARTSWITH` |
+ * | --- | --- | --- |
+ * | `str` | yes | yes |
+ * | every other indexable type | yes | no |
  */
 export class UnsupportedOperatorError extends Error {
   /** The attribute the predicate names. */
@@ -35,9 +34,20 @@ export class UnsupportedOperatorError extends Error {
 }
 
 /**
- * A predicate could not be expressed in the query language for a reason other than its operator —
- * a system attribute that is returned in results but cannot be filtered on, a system attribute
- * compared against the wrong type, or a combinator with nothing to combine.
+ * A predicate or query could not be expressed in the query language for a reason other than its
+ * operator. The main causes:
+ *
+ * - a `$` name that is not a queryable system attribute — one returned in results but never
+ *   indexed (`$createdAt`, `$updatedAt`, `$creationFlags`), or none at all;
+ * - a system attribute compared against the wrong type, or tested with `exists()` / `hasType()`,
+ *   which on a system attribute would be constants;
+ * - a comparison against a `bytes` value, which is never indexed;
+ * - a `BETWEEN` whose bounds have different types;
+ * - a `hasType()` tag that is not an indexable type;
+ * - a combinator with nothing to combine;
+ * - a query with no filter at all — a named schema's tag counts as one;
+ * - through `.from(schema)`, a filter that does not fit the schema: a name that is not a column, a
+ *   column that is not indexed, or a value of another type than the column's.
  */
 export class InvalidPredicateError extends Error {
   /** The attribute the predicate names, where there is one. */
@@ -58,7 +68,7 @@ export class InvalidPredicateError extends Error {
 export type QueryErrorKind =
   /** The query string does not parse. `data` locates it: `{ position, expected, got }`. */
   | "parse"
-  /** A predicate is well-formed but ill-typed — a range operator on an equality-only type, an unknown tag. */
+  /** A predicate is well-formed but ill-typed — `STARTSWITH` on a type other than `str`, `BETWEEN` bounds of different types, an unknown tag. */
   | "type"
   /** A literal failed validation — an `i32` out of range, a bad EIP-55 checksum, more than 18 decimal places. */
   | "literal"

package/src/query/expression.test.ts

@@ -1,9 +1,11 @@
 import { describe, expect, it } from "bun:test"
-import { addr, bytes32, dec, i32, key, str, u64, u256 } from "../attr"
-import { InvalidAttributeNameError } from "../attr/errors"
+import { addr, bytes, bytes32, dec, defineSchema, i32, key, str, u64, u256 } from "../schema"
+import { InvalidAttributeNameError } from "../schema/errors"
 import { InvalidPredicateError, UnsupportedOperatorError } from "./errors"
 import {
   and,
+  between,
+  checkAgainstSchema,
   eq,
   exists,
   gt,
@@ -72,30 +74,29 @@ describe("comparisons", () => {
     expect(String(lte("a", 1))).toBe("a <= i32(1)")
   })
 
-  it("allows range operators only on the ordered types", () => {
+  it("allows range operators on every indexable type", () => {
     expect(String(gt("level", i32(1)))).toBe("level > i32(1)")
     expect(String(gt("balance", u256(1n)))).toBe("balance > u256(1)")
     expect(String(gt("score", dec("1.5")))).toBe("score > dec(1.5)")
-
-    // The node treats a range operator on an equality-only type as a parse error rather than an
-    // empty result, so catching it here saves a round trip for an error code.
-    for (const value of [str("a"), addr(ACCOUNT), key(ENTITY_KEY), bytes32(ENTITY_KEY), true]) {
-      expect(() => gt("a", value)).toThrow(UnsupportedOperatorError)
-    }
-    expect(() => lte("name", "Bob")).toThrow(/does not define <= for a str/)
+    // Ordered as the index orders them: false < true, and unsigned bytes for the rest.
+    expect(String(gte("flagged", true))).toBe("flagged >= true")
+    expect(String(lte("name", "Bob"))).toBe("name <= str('Bob')")
+    expect(String(lt("who", addr(ACCOUNT)))).toBe(`who < addr(${ACCOUNT})`)
+    expect(String(gt("parent", key(ENTITY_KEY)))).toBe(`parent > key(${ENTITY_KEY})`)
+    expect(String(gt("hash", bytes32(ENTITY_KEY)))).toBe(`hash > bytes32(${ENTITY_KEY})`)
   })
 
   it("carries the offending operator and type on the error", () => {
     try {
-      gte("name", "Bob")
+      startsWith("level", i32(1) as never)
       expect.unreachable()
     } catch (error) {
       expect(error).toBeInstanceOf(UnsupportedOperatorError)
       const { attributeName, operator, tag } = error as UnsupportedOperatorError
       expect({ attributeName, operator, tag }).toEqual({
-        attributeName: "name",
-        operator: ">=",
-        tag: "str",
+        attributeName: "level",
+        operator: "STARTSWITH",
+        tag: "i32",
       })
     }
   })
@@ -128,14 +129,16 @@ describe("system attributes", () => {
     expect(() => eq("$expiresAt", 1_200_000n)).toThrow(/write u64\(\.\.\.\) around the value/)
   })
 
-  it("allows range comparisons only on $expiresAt", () => {
-    expect(() => gt("$owner", addr(ACCOUNT))).toThrow(UnsupportedOperatorError)
-    expect(() => gt("$key", key(ENTITY_KEY))).toThrow(UnsupportedOperatorError)
+  it("allows range comparisons on every one", () => {
+    expect(String(gt("$owner", addr(ACCOUNT)))).toBe(`$owner > addr(${ACCOUNT})`)
+    expect(String(lte("$key", key(ENTITY_KEY)))).toBe(`$key <= key(${ENTITY_KEY})`)
   })
 
   it("rejects the ones that are returned but not indexed", () => {
-    for (const name of ["$createdAt", "$updatedAt", "$creationFlags", "$contentType", "$payload"]) {
+    for (const name of ["$createdAt", "$updatedAt", "$creationFlags"]) {
       expect(() => eq(name, 1)).toThrow(/carries no index, so it cannot be filtered on/)
+      // A selection names the entity field, which has no `$`.
+      expect(() => eq(name, 1)).toThrow(`Select it as \`${name.slice(1)}\``)
     }
   })
 
@@ -154,6 +157,48 @@ describe("system attributes", () => {
   })
 })
 
+describe("between", () => {
+  it("renders an inclusive range with both bounds tagged", () => {
+    expect(String(between("score", dec("3.5"), dec("5")))).toBe("score BETWEEN dec(3.5) AND dec(5)")
+    expect(String(between("level", 1, 5))).toBe("level BETWEEN i32(1) AND i32(5)")
+    expect(String(between("name", "a", "m"))).toBe("name BETWEEN str('a') AND str('m')")
+    expect(String(between("$expiresAt", u64(100n), u64(200n)))).toBe(
+      "$expiresAt BETWEEN u64(100) AND u64(200)",
+    )
+  })
+
+  it("is a leaf: its own AND needs no parentheses", () => {
+    expect(String(and(between("a", 1, 5), eq("b", 2)))).toBe(
+      "a BETWEEN i32(1) AND i32(5) AND b = i32(2)",
+    )
+    expect(String(or(between("a", 1, 5), eq("b", 2)))).toBe(
+      "a BETWEEN i32(1) AND i32(5) OR b = i32(2)",
+    )
+    expect(String(not(between("a", 1, 5)))).toBe("NOT a BETWEEN i32(1) AND i32(5)")
+  })
+
+  it("rejects bounds of different types", () => {
+    // @ts-expect-error - both bounds must have one type
+    expect(() => between("score", 1, dec("5"))).toThrow(InvalidPredicateError)
+    expect(() => between("score", 1, dec("5") as never)).toThrow(/a i32 and a dec bound/)
+  })
+
+  it("applies the checks every comparison does", () => {
+    expect(() => between("$owner", ACCOUNT, ACCOUNT)).toThrow(/is a addr, but the value is a str/)
+    expect(() => between("blob", bytes("0x01") as never, bytes("0x02") as never)).toThrow(
+      /bytes are stored but never indexed/,
+    )
+    expect(() => between("not", 1, 2)).toThrow(InvalidAttributeNameError)
+  })
+
+  it("is checked against a schema like a comparison", () => {
+    const Posts = defineSchema({ score: dec().indexed(), title: str() })
+    expect(() => checkAgainstSchema(between("score", dec("1"), dec("2")), Posts)).not.toThrow()
+    expect(() => checkAgainstSchema(between("score", 1, 2), Posts)).toThrow(/asserts a i32/)
+    expect(() => checkAgainstSchema(between("title", "a", "b"), Posts)).toThrow(/not indexed/)
+  })
+})
+
 describe("startsWith", () => {
   it("takes a bare string or a str value", () => {
     expect(String(startsWith("desc", "ab"))).toBe("desc STARTSWITH str('ab')")
@@ -177,8 +222,8 @@ describe("exists and hasType", () => {
   })
 
   it("rejects a type that cannot be set on an attribute", () => {
-    // @ts-expect-error - bytes backs $payload and is never a user attribute
-    expect(() => hasType("blob", "bytes")).toThrow(/is not a settable attribute type/)
+    // @ts-expect-error - bytes is never indexed, so TYPEOF can never see it
+    expect(() => hasType("blob", "bytes")).toThrow(/is not an indexable attribute type/)
     // @ts-expect-error - not a type at all
     expect(() => hasType("age", "int")).toThrow(InvalidPredicateError)
   })
@@ -188,7 +233,7 @@ describe("exists and hasType", () => {
     // `TYPEOF(a) = toString` — a query the node can only answer with a parse error.
     for (const inherited of ["constructor", "toString", "valueOf", "hasOwnProperty"]) {
       // @ts-expect-error - not a type tag
-      expect(() => hasType("age", inherited)).toThrow(/is not a settable attribute type/)
+      expect(() => hasType("age", inherited)).toThrow(/is not an indexable attribute type/)
     }
   })
 
@@ -284,3 +329,66 @@ describe("the expression tree", () => {
     expect(`${expression}`).toBe(render(expression))
   })
 })
+
+describe("bytes", () => {
+  it("cannot be filtered on, bare or tagged — it is never indexed", () => {
+    expect(() => eq("body", new Uint8Array([1]) as never)).toThrow(
+      /bytes are stored but never indexed/,
+    )
+    expect(() => ne("body", bytes("0x01") as never)).toThrow(InvalidPredicateError)
+  })
+})
+
+describe("checkAgainstSchema", () => {
+  const Posts = defineSchema({
+    author: addr().indexed(),
+    category: str().indexed(),
+    score: dec().indexed(),
+    title: str(),
+    body: bytes(),
+  })
+
+  it("accepts indexed columns compared against their own type, and system attributes", () => {
+    expect(() =>
+      checkAgainstSchema(
+        and(
+          eq("category", "docs"),
+          not(gt("score", dec("4"))),
+          or(exists("author"), startsWith("category", "d")),
+          hasType("score", "dec"),
+          eq("$owner", addr(ACCOUNT)),
+        ),
+        Posts,
+      ),
+    ).not.toThrow()
+  })
+
+  it("rejects an unindexed column, saying how to index it", () => {
+    expect(() => checkAgainstSchema(eq("title", "x"), Posts)).toThrow(
+      /"title" is not indexed.*str\(\)\.indexed\(\)/,
+    )
+    // Wherever it hides in the tree.
+    expect(() =>
+      checkAgainstSchema(and(eq("category", "docs"), not(exists("title"))), Posts),
+    ).toThrow(InvalidPredicateError)
+  })
+
+  it("rejects a bytes column without suggesting it be indexed, which bytes never can be", () => {
+    const check = () => checkAgainstSchema(exists("body"), Posts)
+    expect(check).toThrow(InvalidPredicateError)
+    expect(check).toThrow(/"body" is a bytes column, and bytes are stored but never indexed/)
+    expect(check).toThrow(/Index a str, bytes32 or key derived from it instead/)
+    expect(check).not.toThrow(/\.indexed\(\)/)
+  })
+
+  it("rejects a name that is not a column", () => {
+    expect(() => checkAgainstSchema(eq("nope", 1), Posts)).toThrow(/"nope" is not a column/)
+  })
+
+  it("rejects a comparison against a value of another type, which could never match", () => {
+    expect(() => checkAgainstSchema(eq("score", 5), Posts)).toThrow(
+      /"score" is a dec column, but the predicate asserts a i32/,
+    )
+    expect(() => checkAgainstSchema(hasType("score", "i32"), Posts)).toThrow(InvalidPredicateError)
+  })
+})