@minca/core 0.1.17 → 0.2.0

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 (120) hide show
  1. package/README.md +2 -1
  2. package/dist/files/space-files.d.ts +2 -2
  3. package/dist/files/space-files.d.ts.map +1 -1
  4. package/dist/files/space-files.js +7 -5
  5. package/dist/files/space-files.js.map +1 -1
  6. package/dist/inbox/names.d.ts +1 -1
  7. package/dist/inbox/names.js +1 -1
  8. package/dist/index.d.ts +3 -1
  9. package/dist/index.d.ts.map +1 -1
  10. package/dist/index.js +2 -0
  11. package/dist/index.js.map +1 -1
  12. package/dist/node/actions.d.ts +3 -0
  13. package/dist/node/actions.d.ts.map +1 -1
  14. package/dist/node/actions.js.map +1 -1
  15. package/dist/node/api.d.ts +1 -0
  16. package/dist/node/api.d.ts.map +1 -1
  17. package/dist/node/api.js +1 -0
  18. package/dist/node/api.js.map +1 -1
  19. package/dist/node/carrier.js +1 -1
  20. package/dist/node/carrier.js.map +1 -1
  21. package/dist/node/index.d.ts +1 -1
  22. package/dist/node/index.d.ts.map +1 -1
  23. package/dist/node/node-contacts.d.ts.map +1 -1
  24. package/dist/node/node-contacts.js +1 -0
  25. package/dist/node/node-contacts.js.map +1 -1
  26. package/dist/node/node-records.d.ts.map +1 -1
  27. package/dist/node/node-records.js +6 -1
  28. package/dist/node/node-records.js.map +1 -1
  29. package/dist/node/node.d.ts.map +1 -1
  30. package/dist/node/node.js +13 -1
  31. package/dist/node/node.js.map +1 -1
  32. package/dist/node/remote.d.ts.map +1 -1
  33. package/dist/node/remote.js +7 -1
  34. package/dist/node/remote.js.map +1 -1
  35. package/dist/node/space-runtime.d.ts +5 -3
  36. package/dist/node/space-runtime.d.ts.map +1 -1
  37. package/dist/node/space-runtime.js +3 -1
  38. package/dist/node/space-runtime.js.map +1 -1
  39. package/dist/node/types.d.ts +112 -36
  40. package/dist/node/types.d.ts.map +1 -1
  41. package/dist/node/watch-notifications.d.ts +6 -0
  42. package/dist/node/watch-notifications.d.ts.map +1 -1
  43. package/dist/node/watch-notifications.js +47 -9
  44. package/dist/node/watch-notifications.js.map +1 -1
  45. package/dist/query/types.d.ts +1 -0
  46. package/dist/query/types.d.ts.map +1 -1
  47. package/dist/query/types.js.map +1 -1
  48. package/dist/records/contract-builder.d.ts +22 -6
  49. package/dist/records/contract-builder.d.ts.map +1 -1
  50. package/dist/records/contract-builder.js.map +1 -1
  51. package/dist/schemas/automations.d.ts +6 -2
  52. package/dist/schemas/automations.d.ts.map +1 -1
  53. package/dist/schemas/automations.js.map +1 -1
  54. package/dist/schemas/connectors.d.ts +4 -3
  55. package/dist/schemas/connectors.d.ts.map +1 -1
  56. package/dist/schemas/connectors.js +4 -3
  57. package/dist/schemas/connectors.js.map +1 -1
  58. package/dist/schemas/library/media.js +1 -1
  59. package/dist/schemas/library/media.js.map +1 -1
  60. package/dist/session/account-hint.d.ts +2 -2
  61. package/dist/session/account-hint.d.ts.map +1 -1
  62. package/dist/session/account-hint.js +3 -3
  63. package/dist/session/account-hint.js.map +1 -1
  64. package/dist/session/auth.d.ts +7 -3
  65. package/dist/session/auth.d.ts.map +1 -1
  66. package/dist/session/auth.js.map +1 -1
  67. package/dist/session/connection.d.ts +18 -0
  68. package/dist/session/connection.d.ts.map +1 -1
  69. package/dist/session/connection.js +11 -0
  70. package/dist/session/connection.js.map +1 -1
  71. package/dist/session/index.d.ts +2 -2
  72. package/dist/session/index.d.ts.map +1 -1
  73. package/dist/session/index.js +2 -2
  74. package/dist/session/index.js.map +1 -1
  75. package/dist/storage/blob-store.d.ts +3 -0
  76. package/dist/storage/blob-store.d.ts.map +1 -1
  77. package/dist/types.d.ts +11 -2
  78. package/dist/types.d.ts.map +1 -1
  79. package/dist/types.js.map +1 -1
  80. package/docs/README.md +86 -93
  81. package/docs/actions.md +213 -152
  82. package/docs/agents.md +198 -167
  83. package/docs/automations.md +296 -204
  84. package/docs/blueprints-and-guides.md +405 -311
  85. package/docs/bots.md +208 -134
  86. package/docs/building-an-app.md +86 -159
  87. package/docs/collections.md +248 -328
  88. package/docs/computed.md +112 -89
  89. package/docs/contacts.md +151 -112
  90. package/docs/contracts.md +299 -120
  91. package/docs/direct-messages.md +80 -65
  92. package/docs/inbox.md +138 -93
  93. package/docs/node.md +1081 -996
  94. package/docs/permissions.md +142 -0
  95. package/docs/proposing-collections.md +74 -55
  96. package/docs/query-format.md +150 -126
  97. package/docs/records-and-queries.md +205 -126
  98. package/docs/sign-in.md +487 -416
  99. package/docs/spaces.md +261 -246
  100. package/docs/standard-library.md +487 -526
  101. package/docs/storage.md +325 -348
  102. package/docs/usernames.md +164 -97
  103. package/docs/warrants.md +100 -67
  104. package/package.json +1 -6
  105. package/dist/elements/auth-styles.d.ts +0 -18
  106. package/dist/elements/auth-styles.d.ts.map +0 -1
  107. package/dist/elements/auth-styles.js +0 -206
  108. package/dist/elements/auth-styles.js.map +0 -1
  109. package/dist/elements/dom.d.ts +0 -29
  110. package/dist/elements/dom.d.ts.map +0 -1
  111. package/dist/elements/dom.js +0 -91
  112. package/dist/elements/dom.js.map +0 -1
  113. package/dist/elements/index.d.ts +0 -13
  114. package/dist/elements/index.d.ts.map +0 -1
  115. package/dist/elements/index.js +0 -11
  116. package/dist/elements/index.js.map +0 -1
  117. package/dist/elements/minca-auth.d.ts +0 -55
  118. package/dist/elements/minca-auth.d.ts.map +0 -1
  119. package/dist/elements/minca-auth.js +0 -768
  120. package/dist/elements/minca-auth.js.map +0 -1
@@ -1,18 +1,13 @@
1
1
  # The query format
2
2
 
3
- A query is plain JSON data: it can be written by hand, sent over a wire, or
4
- produced by an agent. It runs against the records one node holds of one space.
5
-
6
- > Not protocol: peers never exchange queries, so another implementation may
7
- > offer any query language, and a better one later is not a protocol change.
8
- > Ideas for later, from
9
- > [#28](https://github.com/leifriksheim/minca/issues/28): the interface another query language plugs into, which reports the collections
10
- > it read so a cache ([holding part of a space](node.md#holding-part-of-a-space)) keeps them.
11
- > An [automation](automations.md) keeps a query in a record, and a
12
- > [screen](blueprints-and-guides.md#apps-with-a-screen-of-their-own) passes a `where` to `minca.list`
13
- > (`apps/example/src/components/apps/screens.ts`), so everything that runs
14
- > automations or screens has to read this format the same way; peers that
15
- > only sync and judge the record still never read it.
3
+ This is the full reference for the query JSON that `node.records.query`,
4
+ `watch` and `useQuery` take. For a gentler start, see
5
+ [Records and queries](records-and-queries.md#querying).
6
+
7
+ A query runs against the records one node holds of one space. Peers never
8
+ exchange queries, but [automations](automations.md) and
9
+ [screens](blueprints-and-guides.md#apps-with-a-screen-of-their-own) keep them
10
+ in records, so everything that runs those must read this format the same way.
16
11
 
17
12
  ## Grammar
18
13
 
@@ -55,124 +50,156 @@ Include = { "rel": string,
55
50
  ?"count": boolean }
56
51
  ```
57
52
 
58
- A query is refused, with a reason, before it runs if: it is not an object;
59
- `collection` is missing or empty; a filter is not an object, or `$and`/`$or`
60
- is not a list; a member name starts with `$` and is not `$and`, `$or` or
61
- `$not`; a `@` field is not a MetaField; a `link:` field is not a LinkField; an operator object names an unknown
62
- operator; an include lacks `rel`, has a non-string `from`, a bad `direction`,
63
- or a non-integer or negative `limit`; includes nest more than 3 deep; a `sort`
64
- direction is not `asc`/`desc` or names an unknown `@` field; `limit` is not a
65
- non-negative integer; `cursor` is not a string.
66
-
67
- _Implementation detail:_ the TypeScript API also accepts a definition object
68
- as `collection` or `from`; it is replaced by its `name` before the query runs.
69
- With a definition whose records' type is known, `where` and `sort` are typed
70
- from it: each field a body path, computed field, `@` field or `link:<role>`
71
- it has, each value of that field's type. A misspelled field
72
- or a number compared with a string is a type error. A bare name is untyped.
73
-
74
- ## Candidates
75
-
76
- A query considers the **current, non-deleted** version of every record in
77
- `collection` that stands ([spec 02 §9.5](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)) and whose body this node can read. Records it
78
- cannot open are left out — here and in every include — so a result's `body` is
79
- never `null`.
80
-
81
- > **Planned: leaving out records that do not conform.** Records whose body or
82
- > links do not fit the definition are kept and flagged ([spec 02 §9.6](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)), but queries,
83
- > includes and counts use them like any other, so a tally can count a record
84
- > the definition says is malformed. The plan: queries and includes leave out
85
- > records with `conforms: false` unless the query asks for them (a new
86
- > optional member, e.g. `"nonconforming": true`). Rules are already enforced
87
- > on arrival ([spec 02 §9.4](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)), so this is about shape, not about who wrote it.
53
+ ## Malformed queries
54
+
55
+ A query is refused before it runs, with a reason, when:
56
+
57
+ - it is not an object, or `collection` is missing or empty;
58
+ - a filter is not an object, or `$and` or `$or` is not a list;
59
+ - a member name starts with `$` and is not `$and`, `$or` or `$not`;
60
+ - a `@` field is not one of the MetaFields, or a `link:` field is malformed;
61
+ - an operator object names an unknown operator;
62
+ - an include lacks `rel`, has a `from` that isn't a string, a bad
63
+ `direction`, or a `limit` that isn't a non-negative integer;
64
+ - includes nest more than 3 deep;
65
+ - a `sort` direction is not `asc` or `desc`, or names an unknown `@` field;
66
+ - `limit` is not a non-negative integer, or `cursor` is not a string.
67
+
68
+ ## Definitions in TypeScript
69
+
70
+ In TypeScript you can pass a collection's definition as `collection` or
71
+ `from`. It is replaced by its `name` before the query runs.
72
+
73
+ With a definition, `where` and `sort` are typed from it. Each field must be a
74
+ body path, a computed field, an `@` field or a `link:<role>` it has, and each
75
+ value must have that field's type. A misspelled field, or a number compared
76
+ with a string, is a type error. A collection named by a string is untyped.
77
+
78
+ ## Which records it considers
79
+
80
+ A query considers the current, non-deleted version of every record in
81
+ `collection` that stands and whose body this node can read. Records it can't
82
+ open are left out, here and in every include, so a result's `body` is never
83
+ `null`. What "stands" means is in
84
+ [spec 02 §9.5](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
85
+
86
+ > **Planned: leaving out records that do not conform.** Today a record whose
87
+ > body or links don't fit the definition is flagged `conforms: false` but
88
+ > still counted by queries, includes and counts. The plan is to leave such
89
+ > records out unless the query asks for them, with a new optional member such
90
+ > as `"nonconforming": true`.
88
91
 
89
92
  ## Field values
90
93
 
91
- | Field | Value |
92
- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
93
- | `@key` | the record key |
94
- | `@author` | the DID that signed this version |
95
- | `@root` | the account it acted for |
96
- | `@createdBy` | the root of the record's first version (or null) |
97
- | `@createdAt` | `createdAt` of the record's first version (the creator's clock) |
98
- | `@updatedAt` | `createdAt` of this version |
99
- | `@seq` | `seq` |
100
- | `@collection` | `collection` |
101
- | `link:<rel>` | the `to` of the record's first link with that `rel`, as contracts' `link` and `onePer` read it; missing when it has none. `{ "link:in": key }` finds a channel's messages, `{ "link:in": { "$exists": false } }` those in no channel. |
102
- | `include:<name>` | in an [automation](automations.md)'s `holds` only: what the query's `include` of that name found for the record, a number for a count |
103
- | path | When its first segment names one of the collection's [computed fields](computed.md), start from that field's value and walk the rest; otherwise walk the body. A body member with a computed field's name is never read: a writer can't stand in for what the node works out. Walking: at each segment, the current value must be a non-null object or array, and the segment one of its own member names, or of an array a position (`0`, `1`, …; nothing else, not `length`); otherwise the value is _missing_. |
94
+ | Field | Value |
95
+ | ---------------- | ------------------------------------------------------------------------------ |
96
+ | `@key` | the record key |
97
+ | `@author` | the DID that signed this version |
98
+ | `@root` | the account it acted for |
99
+ | `@createdBy` | the root of the record's first version, or null |
100
+ | `@createdAt` | `createdAt` of the record's first version, by the creator's clock |
101
+ | `@updatedAt` | `createdAt` of this version |
102
+ | `@seq` | `seq` |
103
+ | `@collection` | `collection` |
104
+ | `link:<rel>` | the `to` of the record's first link with that `rel`; missing when it has none |
105
+ | `include:<name>` | in an automation's `holds` only: what that include found, a number for a count |
106
+ | path | a computed field, or a value in the body (see below) |
107
+
108
+ `link:<rel>` reads links the way contracts' `link` and `onePer` do.
109
+ `{ "link:in": key }` finds a channel's messages, and
110
+ `{ "link:in": { "$exists": false } }` the messages in no channel.
111
+
112
+ ### Paths
113
+
114
+ When a path's first segment names one of the collection's
115
+ [computed fields](computed.md), the path starts from that field's value.
116
+ Otherwise it starts from the body. A body member with a computed field's name
117
+ is never read, so a writer can't stand in for what the node works out.
118
+
119
+ At each segment, the current value must be a non-null object or array, and
120
+ the segment one of its own member names, or a position in an array (`0`, `1`,
121
+ and so on, not `length`). Otherwise the value is _missing_.
104
122
 
105
123
  ## Operators
106
124
 
107
- `value` is the field's value (possibly missing); `x` the operand. _Equal_
108
- means deep equality: same JSON type; objects with the same member names
109
- (order ignored) and equal values; arrays with equal elements in order.
110
-
111
- | Operator | Holds when |
112
- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
113
- | bare value `x` | `value` equals `x` |
114
- | `$eq` | `value` equals `x` |
115
- | `$ne` | `value` does not equal `x` — **true for a missing field** |
116
- | `$gt` `$gte` `$lt` `$lte` | both are numbers, or both strings (compared by UTF-16 code units), and the comparison holds. Any other pairing, including missing, is false. |
117
- | `$in` | `x` is a list containing an element equal to `value`, or, when `value` is a list, equal to any of its elements |
118
- | `$nin` | `x` is a list for which `$in` does not hold (false if `x` is not a list) |
119
- | `$exists` | `(value is not missing) == x`. `null` exists. |
120
- | `$contains` | `value` and `x` are strings and `lower(x)` is a substring of `lower(value)`; or `value` is a list with an element equal to `x`. Otherwise false. Not search. |
121
-
122
- > **Planned: full-text search.** `$contains` scans every candidate, which is
123
- > honest at browser scale but is not search. Ranking and prefix matching need
124
- > an inverted index kept beside the records, and a query operator or member
125
- > for it. Not designed. _Open:_ whether the index is a node's local business
126
- > (specified here only as query syntax and result order) or something peers
127
- > share; and, for private spaces, that the index holds plaintext and must be
128
- > kept like the bodies it came from ([05](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md)).
129
-
130
- `$and`, `$or` and `$not` nest at most 16 deep.
131
-
132
- Several operators on one field must all hold; several fields in one filter
133
- must all hold. `$and`: all subfilters hold; `$or`: at least one; `$not`: the
134
- subfilter does not hold.
135
-
136
- ## Sort, limit and cursor
137
-
138
- - `sort` is applied field by field in the **order the members appear** in the
139
- `sort` object (JSON member order is significant here). Default:
140
- `{ "@createdAt": "asc" }`.
141
- - Values compare: missing or `null` first; two numbers numerically; two
142
- booleans `false < true`; anything else by their string forms. `desc`
143
- reverses a field's order (so missing sorts last).
144
- - Ties always break on `@key`, ascending — a total order that is the same on
145
- every node holding the same records.
146
- - `limit` takes at most that many records after the cursor; absent means all.
147
- There is no maximum.
148
- - The result's `cursor` is the key of the last record returned when more
149
- records follow it, else `null`. Passing it back resumes after the record with
150
- that key in the re-sorted candidates.
151
- - If no candidate has the cursor's key any more, the query is meant to resume
152
- from where that record would have been. _Open:_ how "where it
153
- would have been" is found once the record is gone.
154
-
155
- > **Known defect:** when the cursor's key is gone, the reference starts again
156
- > from the first record (`packages/core/src/query/engine.ts`), so a caller paging through
157
- > sees records twice. A fix will resume after the cursor's position.
158
- > Tracked in [#20](https://github.com/leifriksheim/minca/issues/20).
125
+ `value` is the field's value, which may be missing. `x` is the operand.
126
+ _Equal_ means deep equality: the same JSON type, objects with the same member
127
+ names in any order and equal values, arrays with equal elements in order.
128
+
129
+ | Operator | Holds when |
130
+ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
131
+ | bare value `x` | `value` equals `x` |
132
+ | `$eq` | `value` equals `x` |
133
+ | `$ne` | `value` does not equal `x`. **True for a missing field.** |
134
+ | `$gt` `$gte` `$lt` `$lte` | both are numbers, or both strings, and the comparison holds. Otherwise false. |
135
+ | `$in` | `x` is a list with an element equal to `value`, or to any element of a list `value` |
136
+ | `$nin` | `x` is a list and `$in` does not hold. False when `x` is not a list. |
137
+ | `$exists` | `value` is not missing, when `x` is true; is missing, when `x` is false. `null` exists. |
138
+ | `$contains` | a string `value` contains a string `x`, ignoring case; or a list `value` has an element equal to `x`. Otherwise false. |
139
+
140
+ Strings compare by UTF-16 code units. A missing value never passes `$gt`,
141
+ `$gte`, `$lt` or `$lte`.
142
+
143
+ Several operators on one field must all hold, and so must several fields in
144
+ one filter. `$and` holds when all its subfilters do, `$or` when at least one
145
+ does, `$not` when its subfilter doesn't. They nest at most 16 deep.
146
+
147
+ > **Planned: full-text search.** `$contains` scans every candidate, so it is a
148
+ > substring match, not search. Ranking and prefix matching need an index kept
149
+ > beside the records. Not designed yet, including whether peers would share
150
+ > the index, and how a private space would keep its plaintext safe.
151
+
152
+ ## Sort
153
+
154
+ `sort` applies field by field, in the order the members appear in the `sort`
155
+ object. JSON member order matters here. The default is
156
+ `{ "@createdAt": "asc" }`.
157
+
158
+ Values compare like this:
159
+
160
+ - missing or `null` first;
161
+ - two numbers numerically;
162
+ - two booleans `false` before `true`;
163
+ - anything else by their string forms.
164
+
165
+ `desc` reverses a field's order, so missing values sort last. Ties always
166
+ break on `@key`, ascending, so every node holding the same records gives the
167
+ same order.
168
+
169
+ ## Limit and cursor
170
+
171
+ `limit` takes at most that many records after the cursor. Without it you get
172
+ all of them. There is no maximum.
173
+
174
+ The result's `cursor` is the key of the last record returned when more
175
+ follow, else `null`. Pass it back to resume after the record with that key.
176
+
177
+ If the cursor's record is gone, the query is meant to resume from where it
178
+ would have been. How to find that place is still open.
179
+
180
+ > **Known defect:** when the cursor's record is gone, paging starts again from
181
+ > the first record, so you see records twice
182
+ > ([#20](https://github.com/leifriksheim/minca/issues/20)).
159
183
 
160
184
  ## Include
161
185
 
162
- For each record returned, each named include finds related records:
186
+ For each record returned, each named include finds related records.
163
187
 
164
- - `direction: "in"` (default): current, readable, non-deleted records that
165
- have a link `{ rel, to: <this record's key> }`, optionally only those in
166
- `from`; ordered by `@createdAt`, then `@key`.
167
- - `direction: "out"`: this record's own links with that `rel`, in link order,
168
- each resolved to the target's current, readable, non-deleted version,
169
- optionally only those in `from`. A target not held finds nothing.
188
+ - `direction: "in"`, the default, finds records with a link
189
+ `{ rel, to: <this record's key> }`. They come ordered by `@createdAt`, then
190
+ `@key`.
191
+ - `direction: "out"` follows this record's own links with that `rel`, in link
192
+ order. A target this node doesn't hold finds nothing.
170
193
 
171
- Then `where` filters them. With `count: true` the include's value is the
172
- number found (after `where`, ignoring `limit`). Otherwise it is the first
173
- `limit` of them (all when absent), each expanded by its own nested `include`.
174
- Every returned record has an `included` object, empty when there were no
175
- includes.
194
+ Either way, only current, readable, non-deleted records count, and only those
195
+ in `from` when it is given. Then `where` filters them.
196
+
197
+ With `count: true` the include's value is how many it found, after `where`
198
+ and ignoring `limit`. Otherwise it is the first `limit` of them, or all, each
199
+ expanded by its own nested `include`.
200
+
201
+ Every returned record has an `included` object. It is empty when the query
202
+ has no includes.
176
203
 
177
204
  ## Result
178
205
 
@@ -180,9 +207,6 @@ includes.
180
207
  { "records": [ … ], "cursor": "mfrggzdfmztwq2lknnwg23tpoa", "complete": true }
181
208
  ```
182
209
 
183
- `complete` is false only on a node that holds part of a space while a
184
- collection the query needs is still arriving
185
- ([05 — Sync and storage](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md)). The shape of each record
186
- object is the node's record view ([06 — Nodes, sessions and apps](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
187
-
188
- _Source: `packages/core/src/query/types.ts`, `packages/core/src/query/filter.ts` (`checkQuery`, `matches`, `fieldValue`, `MAX_INCLUDE_DEPTH`), `packages/core/src/query/engine.ts` (`runQuery`, `sortRecords`, `expand`). Tests: `packages/core/tests/query.test.ts` (all; "link:<rel> is where the first link…" for link fields), `packages/core/tests/typed-query.test.ts`._
210
+ `complete` is false only on a node that holds part of a space, while a
211
+ collection the query needs is still arriving. Each record has the shape shown
212
+ in [Records and queries](records-and-queries.md#what-a-record-looks-like).