@loradb/lora-node 0.36.0 → 0.36.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/README.md +5 -0
  2. package/docs/README.md +86 -0
  3. package/docs/concepts/graph-model.md +270 -0
  4. package/docs/concepts/nodes.md +285 -0
  5. package/docs/concepts/properties.md +348 -0
  6. package/docs/concepts/relationships.md +325 -0
  7. package/docs/concepts/result-formats.md +183 -0
  8. package/docs/concepts/schema-free.md +183 -0
  9. package/docs/cookbook.md +1081 -0
  10. package/docs/data-types/lists-and-maps.md +406 -0
  11. package/docs/data-types/overview.md +210 -0
  12. package/docs/data-types/scalars.md +376 -0
  13. package/docs/data-types/spatial.md +291 -0
  14. package/docs/data-types/temporal.md +355 -0
  15. package/docs/data-types/vectors.md +563 -0
  16. package/docs/errors.md +183 -0
  17. package/docs/functions/aggregation.md +372 -0
  18. package/docs/functions/list.md +522 -0
  19. package/docs/functions/map.md +207 -0
  20. package/docs/functions/math.md +421 -0
  21. package/docs/functions/number.md +197 -0
  22. package/docs/functions/overview.md +545 -0
  23. package/docs/functions/spatial.md +384 -0
  24. package/docs/functions/string.md +502 -0
  25. package/docs/functions/temporal.md +590 -0
  26. package/docs/functions/utility.md +137 -0
  27. package/docs/functions/vectors.md +772 -0
  28. package/docs/getting-started/installation.md +204 -0
  29. package/docs/getting-started/node.md +582 -0
  30. package/docs/getting-started/tutorial.md +334 -0
  31. package/docs/index.md +203 -0
  32. package/docs/limitations.md +291 -0
  33. package/docs/performance.md +219 -0
  34. package/docs/queries/aggregation.md +520 -0
  35. package/docs/queries/cheat-sheet.md +302 -0
  36. package/docs/queries/constraints.md +239 -0
  37. package/docs/queries/create.md +331 -0
  38. package/docs/queries/examples.md +453 -0
  39. package/docs/queries/index.md +169 -0
  40. package/docs/queries/indexes.md +546 -0
  41. package/docs/queries/match.md +429 -0
  42. package/docs/queries/ordering.md +359 -0
  43. package/docs/queries/parameters.md +328 -0
  44. package/docs/queries/paths.md +462 -0
  45. package/docs/queries/return-with.md +500 -0
  46. package/docs/queries/set-delete.md +369 -0
  47. package/docs/queries/unwind-merge.md +358 -0
  48. package/docs/queries/where.md +416 -0
  49. package/docs/snapshot.md +545 -0
  50. package/docs/troubleshooting.md +1158 -0
  51. package/docs/wal.md +570 -0
  52. package/docs/why.md +273 -0
  53. package/package.json +13 -14
@@ -0,0 +1,137 @@
1
+ ---
2
+ title: "Utility Functions"
3
+ description: "Utility function namespaces in LoraDB, including type and cast helpers, entity introspection, path helpers, text similarity, JSON, bytes, crypto, UUID, number predicates, and bit operations."
4
+ online: "https://loradb.com/docs/functions/utility"
5
+ package: "@loradb/lora-node@0.36.2"
6
+ ---
7
+
8
+ # Utility Functions
9
+
10
+ This page covers the built-in namespaces that do not need a full
11
+ category page of their own. They follow the same rules as the rest of
12
+ the function library: canonical names are namespaced, arguments are
13
+ validated before execution, and most invalid or missing inputs return
14
+ `null`.
15
+
16
+ ## Type, Cast, and Value Helpers
17
+
18
+ | Namespace | Functions |
19
+ |---|---|
20
+ | `type.*` | `type.of(x)`, `type.is(x, TYPE)` |
21
+ | `cast.*` | `cast.to(x, TYPE)`, `cast.try(x, TYPE)`, `cast.can(x, TYPE)` |
22
+ | `value.*` | `value.size(x)`, `value.keys(x)`, `value.properties(x)`, `value.reverse(x)`, `value.coalesce(a, b, ...)`, `value.is_null(x)`, `value.is_not_null(x)`, `value.id(x)`, `value.assert(condition, message)` |
23
+
24
+ ```cypher
25
+ RETURN type.of([1, 2, 3]); // 'LIST<INTEGER>'
26
+ RETURN type.is('2026-05-01'::DATE, DATE); // true
27
+ RETURN cast.try($maybe_int, INTEGER); // null if conversion fails
28
+ RETURN value.coalesce(null, 'fallback') // 'fallback'
29
+ ```
30
+
31
+ ### assert
32
+
33
+ `assert(condition, message)` (also `value.assert`) returns `true` when the
34
+ condition is `true`. Otherwise the statement fails with
35
+ `assertion failed: <message>`, also for `null`: a check that could not be
36
+ decided did not pass. `message` is optional.
37
+
38
+ ```cypher
39
+ MATCH (a:Account {id: $id})
40
+ SET a.balance = a.balance - $amount
41
+ WITH a
42
+ RETURN assert(a.balance >= 0, 'insufficient funds') AS ok
43
+ ```
44
+
45
+ It raises where it is evaluated: in `WHERE`, `WITH`, `RETURN`, `SET`,
46
+ `ORDER BY` and inside aggregates, once per row. A row that `SKIP` or
47
+ `LIMIT` drops before the expression is evaluated is not checked.
48
+
49
+ A failing statement writes nothing, and inside a transaction it rolls
50
+ the transaction back. That turns a check into a statement: a batch sent
51
+ with `db.transaction([...])` can change data and verify the result in
52
+ one call, without a round trip to decide whether to commit.
53
+
54
+ Prefer `value::TYPE`, `CAST(value AS TYPE)`, and
55
+ `TRY_CAST(value AS TYPE)` in handwritten query text. The function forms
56
+ are useful in generated queries where the target type is already being
57
+ assembled as an expression.
58
+
59
+ ## Entity and Path Introspection
60
+
61
+ | Namespace | Functions |
62
+ |---|---|
63
+ | `node.*` | `node.id(n)`, `node.labels(n)`, `node.has_label(n, label)`, `node.keys(n)`, `node.properties(n)` |
64
+ | `edge.*` | `edge.id(r)`, `edge.type(r)`, `edge.keys(r)`, `edge.properties(r)`, `edge.start(r)`, `edge.end(r)` |
65
+ | `path.*` | `path.nodes(p)`, `path.edges(p)`, `path.length(p)`, `path.first(p)`, `path.last(p)` |
66
+ | `value.*` | `value.id(x)`, `value.keys(x)`, `value.properties(x)` for node, relationship, and map inputs |
67
+
68
+ ```cypher
69
+ MATCH p = (a:Person)-[r:KNOWS]->(b:Person)
70
+ RETURN node.labels(a),
71
+ edge.type(r),
72
+ path.length(p),
73
+ path.nodes(p)
74
+ ```
75
+
76
+ The familiar Cypher aliases `id`, `labels`, `type`, `keys`,
77
+ `properties`, and `length` resolve to these canonical helpers.
78
+
79
+ ## Text Similarity and Phonetics
80
+
81
+ | Function | Use |
82
+ |---|---|
83
+ | `text.distance(a, b, metric)` | Edit distance as an integer |
84
+ | `text.similarity(a, b, metric)` | Similarity score as a float |
85
+ | `text.phonetic(s, algorithm)` | Phonetic key |
86
+ | `text.phonetic_match(a, b, algorithm)` | Phonetic equality predicate |
87
+
88
+ ```cypher
89
+ RETURN text.distance('kitten', 'sitting', 'levenshtein'); // 3
90
+ RETURN text.similarity('lora', 'loradb', 'jaro_winkler');
91
+ RETURN text.phonetic_match('Smith', 'Smyth', 'soundex') // true
92
+ ```
93
+
94
+ Supported distance metrics are `levenshtein`, `damerau`, and `hamming`.
95
+ Supported similarity metrics are `levenshtein`, `jaro`, `jaro_winkler`,
96
+ and `sorensen_dice`. The current phonetic algorithm is `soundex`.
97
+
98
+ ## Number and Bit Utilities
99
+
100
+ | Namespace | Functions |
101
+ |---|---|
102
+ | `number.*` | `number.format(n[, precision[, thousands]])`, `number.to_base(n, radix)`, `number.from_base(s, radix)`, `number.to_roman(n)`, `number.from_roman(s)`, `number.is_integer(n)`, `number.is_even(n)`, `number.is_odd(n)`, `number.is_positive(n)`, `number.is_negative(n)`, `number.is_zero(n)`, `number.is_nan(n)`, `number.is_finite(n)`, `number.is_infinite(n)`, `number.bitop(a, op, b)` |
103
+ | `bits.*` | `bits.and(a, b)`, `bits.or(a, b)`, `bits.xor(a, b)`, `bits.shift_left(a, b)`, `bits.shift_right(a, b)`, `bits.not(a)` |
104
+
105
+ ```cypher
106
+ RETURN number.format(12345.678, 2, ','); // '12,345.68'
107
+ RETURN number.to_roman(1994); // 'MCMXCIV'
108
+ RETURN bits.and(12, 10); // 8
109
+ RETURN bits.shift_left(3, 2) // 12
110
+ ```
111
+
112
+ `bits.*` operates on integers. `number.bitop` accepts operation strings
113
+ such as `'and'`, `'or'`, `'xor'`, `'shl'`, `'shr'`, and `'not'`; prefer
114
+ the named `bits.*` forms in new queries. Shifts take 0 to 63 bits, and a
115
+ left shift whose result doesn't fit an integer is an error, as for the
116
+ arithmetic operators.
117
+
118
+ ## Bytes, Crypto, UUID, and JSON
119
+
120
+ | Namespace | Functions |
121
+ |---|---|
122
+ | `bytes.*` | `bytes.size(x)`, `bytes.from_string(s[, encoding])`, `bytes.to_string(bytes[, encoding])`, `bytes.base64_encode(x)`, `bytes.base64_decode(s)`, `bytes.hex_encode(x)`, `bytes.hex_decode(s)`, `bytes.compress(x[, algorithm])`, `bytes.decompress(x[, algorithm])` |
123
+ | `crypto.*` | `crypto.blake3(x)`, `crypto.crc32(x)` |
124
+ | `uuid.*` | `uuid.new()`, `uuid.from_string(s)`, `uuid.is_valid(s)` |
125
+ | `json.*` | `json.encode(x[, pretty])`, `json.decode(s)`, `json.path(x, path)` |
126
+
127
+ ```cypher
128
+ RETURN bytes.base64_encode('lora'); // 'bG9yYQ=='
129
+ RETURN crypto.blake3('lora'); // hex digest string
130
+ RETURN uuid.is_valid(uuid.new()); // true
131
+ RETURN json.path(json.decode('{"a":[10]}'), '$.a[0]') // 10
132
+ ```
133
+
134
+ `bytes.compress` and `bytes.decompress` support `gzip` and `deflate`.
135
+ `json.encode` supports scalar, list, map, and temporal values that can
136
+ be represented in JSON. Graph entities are intentionally not encoded as
137
+ JSON unless you first project the fields you want into a map.