notes

3.9 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. return it.next()
75. }
77. \* Raw iterator over matches. field null → every live record; the pk and any
78. declared index are binary-searched — other fields need an index declared. *\
79. iterate(field, value) {
80. if (field == null) {
81. return #handle.find_all()
82. }
83. if (field == #pk) {
84. return #handle.find_pk(value)
85. }
86. return #handle.find_index(field, value)
87. }
89. \* All matching records as a Hybrid; find(null) answers everything. *\
90. find(field, value) {
91. return drain(iterate(field, value))
92. }
94. \* Ascending index range scan, both bounds inclusive; null bound = open end. *\
95. range(field, low, high) {
96. return drain(#handle.find_range(field, low, high))
97. }
99. \* Lazy Cursor over the same matches — records decode one at a time. *\
100. cursor(field, value) {
101. return {
102. #iter = iterate(field, value);
103. } > new Cursor()
104. }
106. \* Delete every record with this primary key; answers how many went. *\
107. delete(key) {
108. return #handle.delete_pk(key)
109. }
111. \* Replace the record(s) at this pk. `record` must carry the pk (the JS
112. update() contract); answers how many were replaced. A record without it
113. is refused — null, the stored record untouched, lastError() says why. *\
114. update(key, record) {
115. return #handle.update_pk(key, record)
116. }
118. \* Live record count. *\
119. count() {
120. return #handle.count()
121. }
123. \* Rewrite the data file without tombstones and rebuild the indexes. *\
124. compactNow() {
125. #handle.compact()
126. }
128. \* Flush meta/index state to disk now. *\
129. persist() {
130. #handle.persist()
131. }
133. \* Reason for the last failed put/update ('' when none). *\
134. lastError() {
135. return #handle.last_error()
136. }
138. \* Close the database; the closed event fires. *\
139. close() {
140. #handle.close()
141. emit closed(this)
142. }
144. // Internal: collect an iterator into an array.
145. drain(it) {
146. let out = []
147. if (it == null) {
148. return out
149. }
150. for (rec of it) {
151. out.push(rec)
152. }
153. return out
154. }