tickets

4.0 KB

1. \* hl:mpackdb — the MessagePack file database. Construct it and it opens
2. (the file root IS the constructor):
4. db = new MPackDB(file = '/tmp/users.db', primaryKey = '*id',
5. indexes = ['!email', 'age'])
7. Key prefixes follow the JS API: `*name` auto-increment number pk (a fresh
8. table counts from 1; an existing one keeps its stored counter), `@name`
9. uuid pk, plain `name` string pk; a LEADING `!` on an index makes it
10. unique, `*`/`@` on an index select numeric/uuid key parsing. On-disk
11. format is compatible with the JS mpackdb 1.0.7 — a db written by either
12. side is readable and mutable by the other. *\
14. /* Wraps the Zig engine (plugins/mpackdb/{msgpack,engine}.zig, mission 066).
15. `>` / `<>` hydration does NOT run the run body — construct with args. */
17. \* The database is open (fired from the constructor's run body). *\
18. emit opened(
19. MPackDB db \\ this database
20. )
22. \* Opening failed. *\
23. emit error(
24. Hybrid e \\ the failure
25. )
27. \* close() finished. *\
28. emit closed(
29. MPackDB db \\ this database
30. )
32. String file = "" \\ the .db path, script-relative
33. String primaryKey = "" \\ pk declaration: *name | @name | name | '' for none
34. Hybrid indexes = [] \\ index declarations, '!' prefix = unique
35. Boolean compact = true \\ compact the file on open
37. Hybrid #handle
38. String #pk \\ the primary key FIELD NAME, prefixes stripped (null when none)
40. open() {
41. #handle = __native("mpackdb.open", file, primaryKey, indexes, compact)
43. if (#handle != null) {
44. #pk = #handle.pk_name()
45. emit opened(this)
46. } else {
47. emit error(new Error("mpackdb: cannot open " + file))
48. }
49. }
51. open()
53. \* The primary key field name, prefixes stripped (null when none). *\
54. pkField() {
55. return #pk
56. }
58. \* Insert one record. Answers the primary key it was stored under (a
59. generated one for `*`/`@` pks), true for a pk-less db, or null on failure
60. — lastError() has the reason (e.g. a unique-index violation). *\
61. put(
62. Hybrid record \\ the record to store
63. ) {
64. return #handle.insert(record)
65. }
67. \* First record with this primary key, or null. (Named fetch(), not get():
68. `get` is reserved for getter syntax.) *\
69. fetch(key) {
70. let it = #handle.find_pk(key)
71. if (it == null) {
72. return null
73. }
74. let first = it.next()
75. // run it to its end: the plugin frees what the lookup read there (hybriel#126)
76. while (it.next() != null) {}
77. return first
78. }
80. \* Raw iterator over matches. field null → every live record; the pk and any
81. declared index are binary-searched — other fields need an index declared. *\
82. iterate(field, value) {
83. if (field == null) {
84. return #handle.find_all()
85. }
86. if (field == #pk) {
87. return #handle.find_pk(value)
88. }
89. return #handle.find_index(field, value)
90. }
92. \* All matching records as a Hybrid; find(null) answers everything. *\
93. find(field, value) {
94. return drain(iterate(field, value))
95. }
97. \* Ascending index range scan, both bounds inclusive; null bound = open end. *\
98. range(field, low, high) {
99. return drain(#handle.find_range(field, low, high))
100. }
102. \* Lazy Cursor over the same matches — records decode one at a time. *\
103. cursor(field, value) {
104. return {
105. #iter = iterate(field, value);
106. } > new Cursor()
107. }
109. \* Delete every record with this primary key; answers how many went. *\
110. delete(key) {
111. return #handle.delete_pk(key)
112. }
114. \* Replace the record(s) at this pk. `record` must carry the pk (the JS
115. update() contract); answers how many were replaced. A record without it
116. is refused — null, the stored record untouched, lastError() says why. *\
117. update(key, record) {
118. return #handle.update_pk(key, record)
119. }
121. \* Live record count. *\
122. count() {
123. return #handle.count()
124. }
126. \* Rewrite the data file without tombstones and rebuild the indexes. *\
127. compactNow() {
128. #handle.compact()
129. }
131. \* Flush meta/index state to disk now. *\
132. persist() {
133. #handle.persist()
134. }
136. \* Reason for the last failed put/update ('' when none). *\
137. lastError() {
138. return #handle.last_error()
139. }
141. \* Close the database; the closed event fires. *\
142. close() {
143. #handle.close()
144. emit closed(this)
145. }
147. // Internal: collect an iterator into an array.
148. drain(it) {
149. let out = []
150. if (it == null) {
151. return out
152. }
153. for (rec of it) {
154. out.push(rec)
155. }
156. return out
157. }