ident

3.8 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, `@name`
8. uuid pk, plain `name` string pk; a LEADING `!` on an index makes it
9. unique, `*`/`@` on an index select numeric/uuid key parsing. On-disk
10. format is compatible with the JS mpackdb 1.0.7 — a db written by either
11. side is readable and mutable by the other. *\
13. /* Wraps the Zig engine (plugins/mpackdb/{msgpack,engine}.zig, mission 066).
14. `>` / `<>` hydration does NOT run the run body — construct with args. */
16. \* The database is open (fired from the constructor's run body). *\
17. emit opened(
18. MPackDB db \\ this database
19. )
21. \* Opening failed. *\
22. emit error(
23. Hybrid e \\ the failure
24. )
26. \* close() finished. *\
27. emit closed(
28. MPackDB db \\ this database
29. )
31. String file = "" \\ the .db path, script-relative
32. String primaryKey = "" \\ pk declaration: *name | @name | name | '' for none
33. Hybrid indexes = [] \\ index declarations, '!' prefix = unique
34. Boolean compact = true \\ compact the file on open
36. Hybrid #handle
37. String #pk \\ the primary key FIELD NAME, prefixes stripped (null when none)
39. open() {
40. #handle = __native("mpackdb.open", file, primaryKey, indexes, compact)
42. if (#handle != null) {
43. #pk = #handle.pk_name()
44. emit opened(this)
45. } else {
46. emit error(new Error("mpackdb: cannot open " + file))
47. }
48. }
50. open()
52. \* The primary key field name, prefixes stripped (null when none). *\
53. pkField() {
54. return #pk
55. }
57. \* Insert one record. Answers the primary key it was stored under (a
58. generated one for `*`/`@` pks), true for a pk-less db, or null on failure
59. — lastError() has the reason (e.g. a unique-index violation). *\
60. put(
61. Hybrid record \\ the record to store
62. ) {
63. return #handle.insert(record)
64. }
66. \* First record with this primary key, or null. (Named fetch(), not get():
67. `get` is reserved for getter syntax.) *\
68. fetch(key) {
69. let it = #handle.find_pk(key)
70. if (it == null) {
71. return null
72. }
73. return it.next()
74. }
76. \* Raw iterator over matches. field null → every live record; the pk and any
77. declared index are binary-searched — other fields need an index declared. *\
78. iterate(field, value) {
79. if (field == null) {
80. return #handle.find_all()
81. }
82. if (field == #pk) {
83. return #handle.find_pk(value)
84. }
85. return #handle.find_index(field, value)
86. }
88. \* All matching records as a Hybrid; find(null) answers everything. *\
89. find(field, value) {
90. return drain(iterate(field, value))
91. }
93. \* Ascending index range scan, both bounds inclusive; null bound = open end. *\
94. range(field, low, high) {
95. return drain(#handle.find_range(field, low, high))
96. }
98. \* Lazy Cursor over the same matches — records decode one at a time. *\
99. cursor(field, value) {
100. return {
101. #iter = iterate(field, value);
102. } > new Cursor()
103. }
105. \* Delete every record with this primary key; answers how many went. *\
106. delete(key) {
107. return #handle.delete_pk(key)
108. }
110. \* Replace the record(s) at this pk. `record` must carry the pk (the JS
111. update() contract); answers how many were replaced. A record without it
112. is refused — null, the stored record untouched, lastError() says why. *\
113. update(key, record) {
114. return #handle.update_pk(key, record)
115. }
117. \* Live record count. *\
118. count() {
119. return #handle.count()
120. }
122. \* Rewrite the data file without tombstones and rebuild the indexes. *\
123. compactNow() {
124. #handle.compact()
125. }
127. \* Flush meta/index state to disk now. *\
128. persist() {
129. #handle.persist()
130. }
132. \* Reason for the last failed put/update ('' when none). *\
133. lastError() {
134. return #handle.last_error()
135. }
137. \* Close the database; the closed event fires. *\
138. close() {
139. #handle.close()
140. emit closed(this)
141. }
143. // Internal: collect an iterator into an array.
144. drain(it) {
145. let out = []
146. if (it == null) {
147. return out
148. }
149. for (rec of it) {
150. out.push(rec)
151. }
152. return out
153. }