ramdb2-core 2.0.0-alpha.6 → 2.0.0-alpha.8

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # ramdb2-core
2
2
 
3
+ ## 2.0.0-alpha.8
4
+
5
+ ### Minor Changes
6
+
7
+ - f102006: Dotted paths through object relations in a query: `{ orderBy: { 'craCenter.cra.completeName': 'asc' } }`, in `where`, `orderBy`, `groupBy` and aggregates. A missing relation, or a related object the user may not see, reads as null; a `@restricted` field on the path keeps out the rows whose path the user may not read. `RdbCrud` sorts such columns by default (D63).
8
+
9
+ ## 2.0.0-alpha.7
10
+
11
+ ### Minor Changes
12
+
13
+ - 8fa4d07: `@transient(getter: true)`: a getter of the class gives the value of the field, so a query filters and sorts on it (`static transientGetters`), and `RdbCrud` sorts its column by default. ramdb2-server refuses to start when the getter is missing, and refuses in a query a `@transient` resolved by GraphQL only (D62).
14
+
3
15
  ## 2.0.0-alpha.6
4
16
 
5
17
  No changes in this release.
package/README.md CHANGED
@@ -607,6 +607,20 @@ Equality is exact. `$gt` and the like compare strings without case or accents, l
607
607
  values of the same type (`$gt: 5` never matches a string). **A query gives the same result with or without an
608
608
  index**: the index only changes the speed.
609
609
 
610
+ ### Through object relations: dotted paths
611
+
612
+ ```js
613
+ Review.where({ 'book.author.name': 'Hugo' }).orderBy({ 'book.title': 'asc' }).all()
614
+ Review.where().groupBy('book.idAuthor').aggregate({ reviews: { $count: {} } }).run()
615
+ ```
616
+
617
+ A dotted path goes through **object relations** (not lists) to a field of the last object: stored, computed or a
618
+ getter. It works everywhere a query reads a field: `where`, `orderBy`, `groupBy`, aggregates. A missing relation
619
+ reads as `null`: first in an ascending sort, last in a descending one, matched by `{ 'book.title': null }`. No index
620
+ serves a path: the query reads it on every candidate object (a few lookups per object). The option
621
+ `see: obj => boolean` of `store.query` reads an object reached through a path as missing when it returns false
622
+ (ramdb2-server passes its `see` permissions there).
623
+
610
624
  ### Full-text search
611
625
 
612
626
  ```js
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ramdb2-core",
3
- "version": "2.0.0-alpha.6",
3
+ "version": "2.0.0-alpha.8",
4
4
  "description": "In-memory database working directly on hydrated objects, persisted in SQLite",
5
5
  "type": "module",
6
6
  "exports": "./src/index.js",
package/src/DbObject.js CHANGED
@@ -65,6 +65,19 @@ export default class DbObject {
65
65
  */
66
66
  static restrictedFields = []
67
67
 
68
+ /**
69
+ * The @transient fields: not stored, resolved for the GraphQL API by a getter of the class or by a resolver.
70
+ * @type {string[]}
71
+ */
72
+ static transient = []
73
+
74
+ /**
75
+ * The @transient fields whose value is a getter of the class (@transient(getter: true), D62): ramdb2-server
76
+ * checks the getter at start, and lets a query filter and sort on them.
77
+ * @type {string[]}
78
+ */
79
+ static transientGetters = []
80
+
68
81
  /**
69
82
  * The list relations: the table of their objects and the foreign key that points to this object.
70
83
  * @type {Record<string, {table: string, key: string}>}
package/src/index.js CHANGED
@@ -5,5 +5,6 @@ export { default as BucketView } from './indexes/BucketView.js'
5
5
  export { normalize, compareKeys } from './indexes/compare.js'
6
6
  export { TransactionRequiredError, AsyncTransactionError, InvalidStateError, ValidationError, IntegrityError, QueryError } from './errors.js'
7
7
  export { default as QueryBuilder } from './query/QueryBuilder.js'
8
+ export { relationTarget } from './query/path.js'
8
9
  export { required, pattern, oneOf } from './rules.js'
9
10
  export { newMetrics, withMetrics, currentMetrics } from './metrics.js'
@@ -3,6 +3,7 @@ import { compareKeys } from '../indexes/compare.js'
3
3
  import FullTextIndex from '../indexes/FullTextIndex.js'
4
4
  import { compileWhere, sortKey } from './filter.js'
5
5
  import { plan } from './planner.js'
6
+ import { compilePath, readerFor } from './path.js'
6
7
 
7
8
  const QUERY_KEYS = new Set(['where', 'orderBy', 'limit', 'offset', 'groupBy', 'aggregates', 'having'])
8
9
  const AGGREGATES = new Set(['$sum', '$count', '$min', '$max', '$avg'])
@@ -12,6 +13,8 @@ const AGGREGATES = new Set(['$sum', '$count', '$min', '$max', '$avg'])
12
13
  * @property {(obj: any) => boolean} [filter] applied after `where`, e.g. the permissions of the GraphQL layer (D15)
13
14
  * @property {boolean} [countOnly] only `total` is needed: no sort, no pagination
14
15
  * @property {boolean} [explain] returns the plan instead of running the query
16
+ * @property {(obj: any) => boolean} [see] an object reached through a dotted path (D63): false reads it as a missing
17
+ * relation (null)
15
18
  */
16
19
 
17
20
  /**
@@ -31,10 +34,16 @@ export function execute(store, table, query, options = {}, stats) {
31
34
  if (cls === undefined) throw new QueryError(`Unknown table ${table}`)
32
35
  const objects = store._table(table)
33
36
  const indexes = store._indexesOf(table)
34
- const checkField = field => {
35
- if (!isReadable(cls, field)) throw new QueryError(`Unknown field ${field} in ${cls.name}`)
37
+ // Each field checked, each dotted path compiled (D63), once
38
+ let paths
39
+ const pathOf = field => {
40
+ if (!field.includes('.')) return compilePath(store, cls, field)
41
+ paths ??= new Map()
42
+ if (!paths.has(field)) paths.set(field, compilePath(store, cls, field, options.see))
43
+ return paths.get(field)
36
44
  }
37
- const context = { checkField, search: text => search(objects, indexes, text), texts: [], topTexts: [] }
45
+ const readerOf = field => readerFor(field, pathOf(field))
46
+ const context = { pathOf, search: text => search(objects, indexes, text), texts: [], topTexts: [] }
38
47
 
39
48
  const where = query.where ?? {}
40
49
  const test = compileWhere(where, context)
@@ -56,14 +65,15 @@ export function execute(store, table, query, options = {}, stats) {
56
65
 
57
66
  const limit = integer(query, 'limit')
58
67
  const offset = integer(query, 'offset') ?? 0
59
- const aggregates = query.aggregates === undefined ? undefined : compileAggregates(query.aggregates, checkField)
68
+ const aggregates = query.aggregates === undefined ? undefined : compileAggregates(query.aggregates, pathOf)
60
69
 
61
70
  if (query.groupBy !== undefined) {
62
- const groups = group(items, query, aggregates, checkField)
71
+ const groups = group(items, query, aggregates, pathOf)
63
72
  if (options.countOnly) return { total: groups.length }
64
73
  if (query.orderBy !== undefined) {
65
- const order = orderList(query.orderBy, field => checkGroupField(field, query, aggregates))
66
- return { groups: sortedPage(groups, order, (g, field) => groupValues(g)[field], offset, limit), total: groups.length }
74
+ const order = orderList(query.orderBy, field => groupReader(field, query, aggregates))
75
+ const byGroup = order.map(([read, direction]) => [g => read(groupValues(g)), direction])
76
+ return { groups: sortedPage(groups, byGroup, offset, limit), total: groups.length }
67
77
  }
68
78
  return { groups: page(groups, offset, limit), total: groups.length }
69
79
  }
@@ -72,7 +82,7 @@ export function execute(store, table, query, options = {}, stats) {
72
82
 
73
83
  let pageItems
74
84
  if (query.orderBy !== undefined) {
75
- pageItems = sortedPage(items, [...orderList(query.orderBy, checkField), ['id', 'asc']], (obj, field) => obj[field], offset, limit)
85
+ pageItems = sortedPage(items, [...orderList(query.orderBy, readerOf), [obj => obj._f.id, 'asc']], offset, limit)
76
86
  } else if (context.texts.length > 0) {
77
87
  sortByRelevance(items, context.texts)
78
88
  pageItems = page(items, offset, limit)
@@ -85,15 +95,6 @@ export function execute(store, table, query, options = {}, stats) {
85
95
  return result
86
96
  }
87
97
 
88
- // A field a query can read: a getter of the class, persistent or computed
89
- function isReadable(cls, field) {
90
- for (let proto = cls.prototype; proto !== null; proto = Object.getPrototypeOf(proto)) {
91
- const descriptor = Object.getOwnPropertyDescriptor(proto, field)
92
- if (descriptor !== undefined) return typeof descriptor.get === 'function'
93
- }
94
- return false
95
- }
96
-
97
98
  function search(objects, indexes, text) {
98
99
  const index = indexes.all.find(index => index instanceof FullTextIndex)
99
100
  if (index === undefined) throw new QueryError('$text needs a full-text index on the table')
@@ -127,17 +128,16 @@ function page(list, offset, limit) {
127
128
  }
128
129
 
129
130
  /**
130
- * `[{ name: 'asc' }, { id: 'desc' }]` or `{ name: 'asc' }` -> [['name', 'asc'], ...]
131
- * @returns {[string, 'asc' | 'desc'][]}
131
+ * `[{ name: 'asc' }, { id: 'desc' }]` or `{ name: 'asc' }` -> [[read name, 'asc'], ...]
132
+ * @returns {[(item: any) => any, 'asc' | 'desc'][]}
132
133
  */
133
- function orderList(orderBy, checkField) {
134
+ function orderList(orderBy, readerOf) {
134
135
  const list = []
135
136
  for (const part of Array.isArray(orderBy) ? orderBy : [orderBy]) {
136
137
  if (part === null || typeof part !== 'object') throw new QueryError('orderBy expects { field: "asc" | "desc" } objects')
137
138
  for (const [field, direction] of Object.entries(part)) {
138
139
  if (direction !== 'asc' && direction !== 'desc') throw new QueryError(`orderBy ${field}: "asc" or "desc" expected`)
139
- checkField(field)
140
- list.push([field, direction])
140
+ list.push([readerOf(field), direction])
141
141
  }
142
142
  }
143
143
  return list
@@ -147,7 +147,7 @@ function orderList(orderBy, checkField) {
147
147
  * The page `offset, limit` of `list` sorted by `order`. Each value is read once (getters and normalization
148
148
  * are not free). A small page of a long list is selected without sorting the whole list.
149
149
  */
150
- function sortedPage(list, order, valueOf, offset, limit) {
150
+ function sortedPage(list, order, offset, limit) {
151
151
  const compare = (a, b) => {
152
152
  for (let i = 0; i < order.length; i++) {
153
153
  const c = compareKeys(a.keys[i], b.keys[i])
@@ -155,7 +155,7 @@ function sortedPage(list, order, valueOf, offset, limit) {
155
155
  }
156
156
  return 0
157
157
  }
158
- const keyed = item => ({ item, keys: order.map(([field]) => sortKey(valueOf(item, field))) })
158
+ const keyed = item => ({ item, keys: order.map(([read]) => sortKey(read(item))) })
159
159
  const needed = limit === undefined ? Infinity : offset + limit
160
160
 
161
161
  if (needed * 16 < list.length) {
@@ -205,7 +205,7 @@ function sortById(items) {
205
205
  /**
206
206
  * @returns {{name: string, op: string, field?: string}[]}
207
207
  */
208
- function compileAggregates(aggregates, checkField) {
208
+ function compileAggregates(aggregates, pathOf) {
209
209
  if (aggregates === null || typeof aggregates !== 'object') throw new QueryError('aggregates expects an object')
210
210
  return Object.entries(aggregates).map(([name, spec]) => {
211
211
  const entries = spec !== null && typeof spec === 'object' ? Object.entries(spec) : []
@@ -215,14 +215,16 @@ function compileAggregates(aggregates, checkField) {
215
215
  const [op, field] = entries[0]
216
216
  if (op === '$count') return { name, op }
217
217
  if (typeof field !== 'string') throw new QueryError(`Aggregate ${name}: ${op} expects a field name`)
218
- checkField(field)
219
- return { name, op, field }
218
+ const path = pathOf(field)
219
+ return { name, op, field, read: path === undefined ? undefined : readerFor(field, path) }
220
220
  })
221
221
  }
222
222
 
223
223
  function aggregate(items, aggregates) {
224
224
  const result = {}
225
- for (const { name, op, field } of aggregates) {
225
+ for (const { name, op, field, read } of aggregates) {
226
+ // A field of the table read directly, the values of a path read once
227
+ const values = read === undefined ? undefined : items.map(read)
226
228
  switch (op) {
227
229
  case '$count':
228
230
  result[name] = items.length
@@ -231,8 +233,8 @@ function aggregate(items, aggregates) {
231
233
  case '$avg': {
232
234
  let sum = 0
233
235
  let count = 0
234
- for (const obj of items) {
235
- const value = obj[field]
236
+ for (let i = 0; i < items.length; i++) {
237
+ const value = values === undefined ? items[i][field] : values[i]
236
238
  if (typeof value === 'number') {
237
239
  sum += value
238
240
  count++
@@ -245,8 +247,8 @@ function aggregate(items, aggregates) {
245
247
  case '$max': {
246
248
  let best = null
247
249
  let bestKey
248
- for (const obj of items) {
249
- const value = obj[field]
250
+ for (let i = 0; i < items.length; i++) {
251
+ const value = values === undefined ? items[i][field] : values[i]
250
252
  if (value === null || value === undefined) continue
251
253
  const key = sortKey(value)
252
254
  const c = best === null ? 0 : compareKeys(key, bestKey)
@@ -263,14 +265,17 @@ function aggregate(items, aggregates) {
263
265
  return result
264
266
  }
265
267
 
266
- function group(items, query, aggregates, checkField) {
268
+ function group(items, query, aggregates, pathOf) {
267
269
  const fields = Array.isArray(query.groupBy) ? query.groupBy : [query.groupBy]
268
270
  if (fields.length === 0) throw new QueryError('groupBy expects at least one field')
269
- for (const field of fields) checkField(field)
271
+ const paths = fields.map(pathOf)
272
+ const reads = paths.some(path => path !== undefined) ? fields.map((field, i) => readerFor(field, paths[i])) : undefined
270
273
 
271
274
  const buckets = new Map()
272
275
  for (const obj of items) {
273
- const id = fields.length === 1 ? obj[fields[0]] : JSON.stringify(fields.map(field => obj[field]))
276
+ const id = reads === undefined
277
+ ? fields.length === 1 ? obj[fields[0]] : JSON.stringify(fields.map(field => obj[field]))
278
+ : reads.length === 1 ? reads[0](obj) : JSON.stringify(reads.map(read => read(obj)))
274
279
  let bucket = buckets.get(id)
275
280
  if (bucket === undefined) {
276
281
  bucket = { obj, items: [] }
@@ -282,14 +287,14 @@ function group(items, query, aggregates, checkField) {
282
287
  let groups = []
283
288
  for (const { obj, items: members } of buckets.values()) {
284
289
  const key = {}
285
- for (const field of fields) key[field] = obj[field]
290
+ fields.forEach((field, i) => { key[field] = reads === undefined ? obj[field] : reads[i](obj) })
286
291
  groups.push({ key, ...(aggregates === undefined ? {} : aggregate(members, aggregates)) })
287
292
  }
288
293
 
289
294
  if (query.having !== undefined) {
290
295
  // having reads the aggregates, then the fields of the key
291
296
  const context = {
292
- checkField: field => checkGroupField(field, query, aggregates),
297
+ pathOf: field => { checkGroupField(field, query, aggregates) },
293
298
  search: () => { throw new QueryError('$text is not allowed in having') },
294
299
  texts: [],
295
300
  topTexts: [],
@@ -306,6 +311,13 @@ function groupValues(group) {
306
311
  return { ...key, ...values }
307
312
  }
308
313
 
314
+ // A field of a group (see groupValues), for orderBy
315
+ function groupReader(field, query, aggregates) {
316
+ checkGroupField(field, query, aggregates)
317
+ return values => values[field]
318
+ }
319
+
320
+ // A field of a group, for having and orderBy: a field of the key, or an aggregate
309
321
  function checkGroupField(field, query, aggregates) {
310
322
  const fields = Array.isArray(query.groupBy) ? query.groupBy : [query.groupBy]
311
323
  if (fields.includes(field) || aggregates?.some(a => a.name === field)) return
@@ -8,7 +8,8 @@ const LOGICAL = new Set(['$and', '$or', '$nor'])
8
8
 
9
9
  /**
10
10
  * @typedef {object} FilterContext
11
- * @property {(field: string) => void} checkField throws on an unknown field
11
+ * @property {(field: string) => import('./path.js').Path | undefined} pathOf checks a field (throws on an unknown one);
12
+ * a dotted path through object relations (D63) gives its compiled path
12
13
  * @property {(text: {$search: string, $path?: string | string[]}) => Map<object, number>} search objects found, with their score
13
14
  * @property {Map<object, number>[]} texts filled with the results of every $text, for the relevance order
14
15
  * @property {Map<object, number>[]} topTexts the same for the $text every result must meet, for the planner
@@ -37,8 +38,8 @@ export function compileWhere(where, context, top = true) {
37
38
  } else if (key.startsWith('$')) {
38
39
  throw new QueryError(`Unknown operator ${key}`)
39
40
  } else {
40
- context.checkField(key)
41
- tests.push(compileField(key, value))
41
+ const path = context.pathOf(key)
42
+ tests.push(path === undefined ? compileField(key, value) : onPath(path, value))
42
43
  }
43
44
  }
44
45
  return every(tests)
@@ -60,6 +61,13 @@ function isOperatorObject(value) {
60
61
  return keys.length > 0 && keys.every(key => key.startsWith('$'))
61
62
  }
62
63
 
64
+ // A condition on the last field of a path, tested on the last object; a missing relation reads as null
65
+ function onPath({ walk, last }, condition) {
66
+ const test = compileField(last, condition)
67
+ const missing = { [last]: null }
68
+ return obj => test(walk(obj) ?? missing)
69
+ }
70
+
63
71
  function compileField(field, condition) {
64
72
  const options = isOperatorObject(condition) ? condition.$options : undefined
65
73
  const tests = []
@@ -0,0 +1,98 @@
1
+ import { QueryError } from '../errors.js'
2
+
3
+ // The value of a field for a query: a field of the table, or a dotted path through object relations
4
+ // (`craCenter.cra.completeName`, D63). Compiled once per query into a function of the object.
5
+
6
+ /**
7
+ * @typedef {object} Path a dotted path, compiled
8
+ * @property {(obj: any) => any} walk the last object of the path, or null when a relation is missing or not seen
9
+ * @property {string} last the field read on that object
10
+ */
11
+
12
+ /**
13
+ * Checks a field or a path. A field of the table gives undefined: it is read directly (obj[field]), the fastest.
14
+ * @param {import('../Store.js').Store} store
15
+ * @param {Function} cls the class of the table queried
16
+ * @param {string} field
17
+ * @param {(obj: any) => boolean} [see] an object reached through a path: false reads it as a missing relation
18
+ * @returns {Path | undefined}
19
+ */
20
+ export function compilePath(store, cls, field, see) {
21
+ if (!field.includes('.')) {
22
+ checkReadable(cls, field, field)
23
+ return undefined
24
+ }
25
+ const steps = pathSteps(store, cls, field)
26
+ const last = steps.pop()
27
+ const walk = obj => {
28
+ let current = obj
29
+ for (const relation of steps) {
30
+ current = current[relation]
31
+ if (current === null || current === undefined || (see !== undefined && !see(current))) return null
32
+ }
33
+ return current
34
+ }
35
+ return { walk, last }
36
+ }
37
+
38
+ /**
39
+ * The value of a field or a path for an object.
40
+ * @param {string} field
41
+ * @param {Path | undefined} path
42
+ * @returns {(obj: any) => any}
43
+ */
44
+ export function readerFor(field, path) {
45
+ if (path === undefined) return obj => obj[field]
46
+ const { walk, last } = path
47
+ return obj => {
48
+ const target = walk(obj)
49
+ return target === null ? null : target[last]
50
+ }
51
+ }
52
+
53
+ /**
54
+ * The fields of a dotted path, checked: object relations, then a field readable by a query.
55
+ * @param {import('../Store.js').Store} store
56
+ * @param {Function} cls
57
+ * @param {string} path
58
+ * @returns {string[]}
59
+ */
60
+ export function pathSteps(store, cls, path) {
61
+ const steps = path.split('.')
62
+ let current = cls
63
+ for (let i = 0; i < steps.length - 1; i++) {
64
+ const target = relationTarget(current, steps[i])
65
+ if (target === undefined) throw new QueryError(`${path}: ${steps[i]} is not an object relation of ${current.name}`)
66
+ const next = store._classes.get(target)
67
+ if (next === undefined) throw new QueryError(`${path}: unknown table ${target}`)
68
+ current = next
69
+ }
70
+ checkReadable(current, steps.at(-1), path)
71
+ return steps
72
+ }
73
+
74
+ /**
75
+ * The table of the object relation `name` of a class (its foreign key is id + Name), or undefined.
76
+ * @param {{foreignKeys: Record<string, {table: string}>}} cls
77
+ * @param {string} name
78
+ * @returns {string | undefined}
79
+ */
80
+ export function relationTarget(cls, name) {
81
+ if (name === '' || name.startsWith('id')) return undefined
82
+ return cls.foreignKeys[`id${name[0].toUpperCase()}${name.slice(1)}`]?.table
83
+ }
84
+
85
+ function checkReadable(cls, field, path) {
86
+ if (!isReadable(cls, field)) {
87
+ throw new QueryError(path === field ? `Unknown field ${field} in ${cls.name}` : `${path}: unknown field ${field} in ${cls.name}`)
88
+ }
89
+ }
90
+
91
+ // A field a query can read: a getter of the class, persistent or computed
92
+ function isReadable(cls, field) {
93
+ for (let proto = cls.prototype; proto !== null; proto = Object.getPrototypeOf(proto)) {
94
+ const descriptor = Object.getOwnPropertyDescriptor(proto, field)
95
+ if (descriptor !== undefined) return typeof descriptor.get === 'function'
96
+ }
97
+ return false
98
+ }