@appweaver/data 2.5.0 → 2.6.1

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 (60) hide show
  1. package/README.md +4 -2
  2. package/config.d.ts +1 -0
  3. package/config.js +1 -0
  4. package/database/database-config.d.ts +9 -0
  5. package/database/database-config.js +56 -1
  6. package/database/database-error.d.ts +8 -0
  7. package/database/database-error.js +18 -0
  8. package/database/prisma-database.js +16 -5
  9. package/database/setup-database.d.ts +23 -0
  10. package/database/setup-database.js +59 -0
  11. package/database/sqlserver-extension.js +21 -107
  12. package/database/telemetry-extension.d.ts +10 -0
  13. package/database/telemetry-extension.js +52 -0
  14. package/export/export-service.js +4 -0
  15. package/factory/create-model.d.ts +1 -1
  16. package/factory/create-model.js +75 -4
  17. package/factory/create-service.js +8 -0
  18. package/index.d.ts +2 -0
  19. package/index.js +5 -0
  20. package/internal.d.ts +2 -0
  21. package/internal.js +3 -1
  22. package/module.js +6 -3
  23. package/package.json +3 -3
  24. package/resource/resource-service.d.ts +32 -7
  25. package/resource/resource-service.js +244 -35
  26. package/resource/schemas/resource-filter-schema.d.ts +8 -0
  27. package/resource/schemas/resource-filter-schema.js +40 -1
  28. package/resource/schemas/resource-sort-schema.js +10 -0
  29. package/resource/utils/cursor-util.d.ts +13 -0
  30. package/resource/utils/cursor-util.js +21 -0
  31. package/resource/utils/filter-util.d.ts +9 -0
  32. package/resource/utils/filter-util.js +17 -0
  33. package/resource/utils/sort-util.d.ts +14 -0
  34. package/resource/utils/sort-util.js +1 -0
  35. package/resource/utils/where-util.d.ts +20 -0
  36. package/resource/utils/where-util.js +210 -0
  37. package/seeder/create-seeder.d.ts +3 -0
  38. package/seeder/create-seeder.js +1 -1
  39. package/seeder/seeder.d.ts +4 -2
  40. package/seeder/seeder.js +56 -23
  41. package/spatial/geo-schema.d.ts +22 -0
  42. package/spatial/geo-schema.js +60 -0
  43. package/spatial/spatial-config.d.ts +21 -0
  44. package/spatial/spatial-config.js +52 -0
  45. package/spatial/spatial-engine.d.ts +78 -0
  46. package/spatial/spatial-engine.js +232 -0
  47. package/spatial/spatial-extension.d.ts +10 -0
  48. package/spatial/spatial-extension.js +100 -0
  49. package/spatial/spatial-service.d.ts +54 -0
  50. package/spatial/spatial-service.js +213 -0
  51. package/spatial/utils/box-util.d.ts +31 -0
  52. package/spatial/utils/box-util.js +62 -0
  53. package/timeseries/database-time-series.js +2 -13
  54. package/timeseries/timescale-config.d.ts +1 -1
  55. package/timeseries/timescale-time-series.d.ts +6 -4
  56. package/timeseries/timescale-time-series.js +46 -19
  57. package/utils/schema-util.d.ts +8 -0
  58. package/utils/schema-util.js +22 -0
  59. package/utils/write-data-util.d.ts +22 -0
  60. package/utils/write-data-util.js +144 -0
@@ -0,0 +1,232 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.PostgisSpatialEngine = exports.DatabaseSpatialEngine = exports.SpatialEngine = void 0;
4
+ exports.geometryTrigger = geometryTrigger;
5
+ const common_1 = require("@appweaver/common");
6
+ const database_config_1 = require("../database/database-config");
7
+ const database_error_1 = require("../database/database-error");
8
+ const schema_util_1 = require("../utils/schema-util");
9
+ const spatial_config_1 = require("./spatial-config");
10
+ const box_util_1 = require("./utils/box-util");
11
+ const logger = (0, common_1.createLogger)('spatial');
12
+ /** The records a batch of the `database` engine reads. */
13
+ const SCAN_BATCH = 1000;
14
+ /**
15
+ * Finds the records whose geo field matches a spatial condition, for the `_near`, `_within` and `_intersects`
16
+ * operators of the resource queries.
17
+ */
18
+ class SpatialEngine {
19
+ _db;
20
+ constructor(_db) {
21
+ this._db = _db;
22
+ }
23
+ }
24
+ exports.SpatialEngine = SpatialEngine;
25
+ /**
26
+ * The `database` engine, running on every database: the bounding box columns of a geo field narrow the records in a
27
+ * query of the database, then each geometry is matched in the application.
28
+ */
29
+ class DatabaseSpatialEngine extends SpatialEngine {
30
+ async setup() { }
31
+ async match(model, field, condition, limit) {
32
+ const delegate = this._db.client()[(0, common_1.uncapitalize)(model.name)];
33
+ const boxes = (0, common_1.conditionBoxes)(condition);
34
+ const where = condition.operator === 'within'
35
+ ? (0, box_util_1.boxWithinFilter)(field, boxes)
36
+ : (0, box_util_1.boxOverlapFilter)(field, boxes, model.fields[field].type === 'point');
37
+ const matches = [];
38
+ let cursor;
39
+ for (;;) {
40
+ const rows = await delegate.findMany({
41
+ where,
42
+ select: { id: true, [field]: true },
43
+ orderBy: { id: 'asc' },
44
+ take: SCAN_BATCH,
45
+ ...(cursor === undefined ? {} : { cursor: { id: cursor }, skip: 1 })
46
+ });
47
+ for (const row of rows) {
48
+ const geometry = row[field];
49
+ const matched = geometry
50
+ ? (0, common_1.matchSpatialCondition)(geometry, condition)
51
+ : false;
52
+ if (matched !== false) {
53
+ matches.push(typeof matched === 'number'
54
+ ? { id: row.id, distance: matched }
55
+ : { id: row.id });
56
+ }
57
+ }
58
+ // Past the limit, the caller rejects the condition anyway
59
+ if (rows.length < SCAN_BATCH || matches.length > limit) {
60
+ break;
61
+ }
62
+ cursor = rows[rows.length - 1].id;
63
+ }
64
+ return condition.operator === 'near' ? sortByDistance(matches) : matches;
65
+ }
66
+ }
67
+ exports.DatabaseSpatialEngine = DatabaseSpatialEngine;
68
+ /**
69
+ * The `postgis` engine, for PostgreSQL with the PostGIS extension: a trigger keeps a geometry column of each geo field
70
+ * in line with its GeoJSON, indexed with GiST and queried with the functions of PostGIS. The distances are measured on
71
+ * a sphere, like the `database` engine.
72
+ */
73
+ class PostgisSpatialEngine extends SpatialEngine {
74
+ /** @internal */
75
+ _schema = (0, schema_util_1.postgresSchema)((0, common_1.resolveDatabaseType)(database_config_1.databaseConfig.TYPE, database_config_1.databaseConfig.URL));
76
+ /**
77
+ * Creates the trigger writing the geometry columns of every model whose trigger is missing or out of date, and
78
+ * writes the geometries of its records missing them, under an advisory lock, so the instances starting together
79
+ * set them up once. A start with every trigger in place changes nothing.
80
+ *
81
+ * @throws {ConfigurationError} `CONFIGURATION_INVALID` when the PostGIS extension is not installed, or a trigger is
82
+ * out of date and the user of the connection lacks the privileges to replace it.
83
+ */
84
+ async setup(models) {
85
+ if (models.length === 0) {
86
+ return;
87
+ }
88
+ const rows = await this._db
89
+ .client()
90
+ .$queryRawUnsafe(`SELECT extversion FROM pg_extension WHERE extname = 'postgis'`);
91
+ if (rows.length === 0) {
92
+ throw new common_1.ConfigurationError(common_1.ErrorCode.ConfigurationInvalid, 'The postgis extension is not installed in the database, apply the migrations of the generated schema, ' +
93
+ 'which create it, or set spatial.provider to database');
94
+ }
95
+ const updated = await this._db
96
+ .transaction(async (tx) => {
97
+ await tx.$executeRawUnsafe(`SELECT pg_advisory_xact_lock(hashtext('appweaver:spatial'))`);
98
+ const existing = await tx.$queryRawUnsafe(`SELECT c.relname AS "table", p.prosrc AS "source" FROM pg_trigger t ` +
99
+ `JOIN pg_class c ON c.oid = t.tgrelid JOIN pg_namespace n ON n.oid = c.relnamespace ` +
100
+ `JOIN pg_proc p ON p.oid = t.tgfoid WHERE NOT t.tgisinternal ` +
101
+ `AND n.nspname = COALESCE($1::text, current_schema()) AND t.tgname = left(c.relname, 50) || '_geo_sync'`, this._schema ?? null);
102
+ const sources = new Map(existing.map((row) => [row.table, row.source]));
103
+ const updated = [];
104
+ for (const model of models) {
105
+ const trigger = geometryTrigger(model.table, Object.keys(model.fields), this._schema);
106
+ if (sources.get(model.table) === trigger.source) {
107
+ continue;
108
+ }
109
+ for (const statement of trigger.statements) {
110
+ await tx.$executeRawUnsafe(statement);
111
+ }
112
+ updated.push(model.name);
113
+ }
114
+ return updated;
115
+ },
116
+ // The geometries of a large table written for the first time
117
+ { timeout: spatial_config_1.spatialConfig.SETUP_TIMEOUT })
118
+ .catch((error) => {
119
+ if ((0, database_error_1.isPrivilegeError)(error)) {
120
+ throw new common_1.ConfigurationError(common_1.ErrorCode.ConfigurationInvalid, 'The spatial geometry triggers are not up to date, and the database user lacks the privileges to ' +
121
+ 'create them, run `weaver migrate`, which creates them with the user of database.migrationUrl', undefined, { cause: error });
122
+ }
123
+ throw error;
124
+ });
125
+ if (updated.length > 0) {
126
+ logger.info({ models: updated }, 'Spatial geometry triggers set up');
127
+ }
128
+ }
129
+ async match(model, field, condition, limit) {
130
+ const geom = quote((0, common_1.geoColumns)(field).geom);
131
+ const params = [];
132
+ const param = (value, type) => {
133
+ params.push(value);
134
+ return `$${params.length}::${type}`;
135
+ };
136
+ const geometry = (value) => `ST_SetSRID(ST_GeomFromGeoJSON(${param(JSON.stringify(value), 'text')}), 4326)`;
137
+ // The boxes of the condition, which the GiST index narrows the records by
138
+ const boxes = (0, common_1.conditionBoxes)(condition)
139
+ .map((box) => `${geom} && ST_MakeEnvelope(${box.map((value) => param(value, 'float8')).join(', ')}, 4326)`)
140
+ .join(' OR ');
141
+ let predicate;
142
+ let distance = '';
143
+ switch (condition.operator) {
144
+ case 'near': {
145
+ const [lng, lat] = condition.point;
146
+ const point = `ST_SetSRID(ST_MakePoint(${param(lng, 'float8')}, ${param(lat, 'float8')}), 4326)::geography`;
147
+ distance = `ST_Distance(${geom}::geography, ${point}, false)`;
148
+ predicate = `ST_DWithin(${geom}::geography, ${point}, ${param(condition.maxDistance, 'float8')}, false)`;
149
+ if (condition.minDistance) {
150
+ predicate += ` AND ${distance} >= ${param(condition.minDistance, 'float8')}`;
151
+ }
152
+ break;
153
+ }
154
+ case 'within':
155
+ predicate = `ST_CoveredBy(${geom}, ${geometry(condition.geometry)})`;
156
+ break;
157
+ case 'intersects':
158
+ predicate = `ST_Intersects(${geom}, ${geometry(condition.geometry)})`;
159
+ break;
160
+ }
161
+ const sql = `SELECT "id" AS "id"${distance ? `, ${distance} AS "distance"` : ''} ` +
162
+ `FROM ${qualified(model.table, this._schema)} WHERE (${boxes}) AND ${predicate} ` +
163
+ `ORDER BY ${distance ? '"distance", ' : ''}"id" LIMIT ${limit + 1}`;
164
+ const rows = await this._db
165
+ .client()
166
+ .$queryRawUnsafe(sql, ...params);
167
+ return rows.map((row) => distance ? { id: row.id, distance: Number(row.distance) } : { id: row.id });
168
+ }
169
+ }
170
+ exports.PostgisSpatialEngine = PostgisSpatialEngine;
171
+ /**
172
+ * Builds the trigger of a table writing the geometry column of each geo field from its GeoJSON, on an insert and on
173
+ * an update changing the GeoJSON. Its function reads the columns directly, so a write of the other columns costs a
174
+ * comparison only, and does nothing once a migration dropped one of its columns, until the next start replaces it.
175
+ *
176
+ * @param {string} table - The table name.
177
+ * @param {string[]} fields - The geo fields.
178
+ * @param {string} [schema] - The schema of the table, the one of the connection by default.
179
+ * @return {GeometryTrigger} The source of the function and the statements creating the trigger.
180
+ */
181
+ function geometryTrigger(table, fields, schema) {
182
+ // Within the 63 characters of a PostgreSQL name
183
+ const name = `${table.slice(0, 50)}_geo_sync`;
184
+ const qualifiedTable = qualified(table, schema);
185
+ const fn = qualified(name, schema);
186
+ const geometry = (json) => `CASE WHEN jsonb_typeof(${json}::jsonb) = 'object' THEN ST_SetSRID(ST_GeomFromGeoJSON(${json}::text), 4326) END`;
187
+ const assign = (field) => `NEW.${quote((0, common_1.geoColumns)(field).geom)} := ${geometry(`NEW.${quote(field)}`)};`;
188
+ const source = [
189
+ '',
190
+ 'BEGIN',
191
+ ` IF TG_OP = 'INSERT' THEN`,
192
+ ...fields.map((field) => ` ${assign(field)}`),
193
+ ' ELSE',
194
+ ...fields.flatMap((field) => [
195
+ ` IF NEW.${quote(field)} IS DISTINCT FROM OLD.${quote(field)} THEN`,
196
+ ` ${assign(field)}`,
197
+ ' END IF;'
198
+ ]),
199
+ ' END IF;',
200
+ ' RETURN NEW;',
201
+ // A column a migration dropped
202
+ 'EXCEPTION WHEN undefined_column THEN',
203
+ ' RETURN NEW;',
204
+ 'END',
205
+ ''
206
+ ].join('\n');
207
+ return {
208
+ source,
209
+ statements: [
210
+ `CREATE OR REPLACE FUNCTION ${fn}() RETURNS trigger AS $$${source}$$ LANGUAGE plpgsql`,
211
+ `DROP TRIGGER IF EXISTS ${quote(name)} ON ${qualifiedTable}`,
212
+ `CREATE TRIGGER ${quote(name)} BEFORE INSERT OR UPDATE ON ${qualifiedTable} FOR EACH ROW EXECUTE FUNCTION ${fn}()`,
213
+ ...fields.map((field) => {
214
+ const geom = quote((0, common_1.geoColumns)(field).geom);
215
+ return (`UPDATE ${qualifiedTable} SET ${geom} = ${geometry(quote(field))} ` +
216
+ `WHERE ${geom} IS NULL AND jsonb_typeof(${quote(field)}::jsonb) = 'object'`);
217
+ })
218
+ ]
219
+ };
220
+ }
221
+ /** Orders the matches of a `near` condition by their distance, then by their id. */
222
+ function sortByDistance(matches) {
223
+ return matches.sort((a, b) => a.distance - b.distance ||
224
+ (a.id === b.id ? 0 : a.id < b.id ? -1 : 1));
225
+ }
226
+ /** The quoted name of a table or a function, qualified by its schema when given. */
227
+ function qualified(name, schema) {
228
+ return schema ? `${quote(schema)}.${quote(name)}` : quote(name);
229
+ }
230
+ function quote(name) {
231
+ return `"${name.replace(/"/g, '""')}"`;
232
+ }
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Creates the Prisma client extension of the geo fields. Every write checks the values of the geo fields and
3
+ * normalizes them into GeoJSON geometries (a `{ lat, lng }` object into a point), storing a null as the database null
4
+ * of a JSON column, and writes the bounding box columns of each geo field, which are left out of the results. The
5
+ * PostGIS geometry columns of the `postgis` provider are written by a trigger of the database (see
6
+ * `PostgisSpatialEngine`).
7
+ *
8
+ * @return {Object} The Prisma client extension.
9
+ */
10
+ export declare function spatialExtension(): any;
@@ -0,0 +1,100 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.spatialExtension = spatialExtension;
4
+ const client_1 = require("@prisma/client/runtime/client");
5
+ const common_1 = require("@appweaver/common");
6
+ const internal_1 = require("@appweaver/core/internal");
7
+ const write_data_util_1 = require("../utils/write-data-util");
8
+ const spatial_config_1 = require("./spatial-config");
9
+ // The operations whose result holds no records
10
+ const COUNT_OPERATIONS = new Set([
11
+ 'count',
12
+ 'aggregate',
13
+ 'groupBy',
14
+ 'createMany',
15
+ 'updateMany',
16
+ 'deleteMany'
17
+ ]);
18
+ /**
19
+ * Creates the Prisma client extension of the geo fields. Every write checks the values of the geo fields and
20
+ * normalizes them into GeoJSON geometries (a `{ lat, lng }` object into a point), storing a null as the database null
21
+ * of a JSON column, and writes the bounding box columns of each geo field, which are left out of the results. The
22
+ * PostGIS geometry columns of the `postgis` provider are written by a trigger of the database (see
23
+ * `PostgisSpatialEngine`).
24
+ *
25
+ * @return {Object} The Prisma client extension.
26
+ */
27
+ function spatialExtension() {
28
+ const normalizeRecord = (modelName, data) => {
29
+ const geoFields = geoFieldsOf(modelName);
30
+ if (!geoFields) {
31
+ return data;
32
+ }
33
+ const normalized = { ...data };
34
+ for (const [field, geo] of Object.entries(geoFields)) {
35
+ const value = data[field];
36
+ if (value === undefined) {
37
+ continue;
38
+ }
39
+ const geometry = isNullValue(value)
40
+ ? null
41
+ : normalizeValue(modelName, field, value, geo.type);
42
+ normalized[field] = geometry ?? client_1.DbNull;
43
+ const columns = (0, common_1.geoColumns)(field);
44
+ const box = geometry ? (0, common_1.geometryBox)(geometry) : [null, null, null, null];
45
+ normalized[columns.minLng] = box[0];
46
+ normalized[columns.minLat] = box[1];
47
+ normalized[columns.maxLng] = box[2];
48
+ normalized[columns.maxLat] = box[3];
49
+ }
50
+ return normalized;
51
+ };
52
+ const stripRecord = (modelName, record) => {
53
+ const geoFields = geoFieldsOf(modelName);
54
+ for (const field of Object.keys(geoFields ?? {})) {
55
+ const columns = (0, common_1.geoColumns)(field);
56
+ delete record[columns.minLng];
57
+ delete record[columns.minLat];
58
+ delete record[columns.maxLng];
59
+ delete record[columns.maxLat];
60
+ }
61
+ return record;
62
+ };
63
+ return {
64
+ name: 'appweaver-spatial',
65
+ query: {
66
+ $allModels: {
67
+ async $allOperations({ model, operation, args, query }) {
68
+ const result = await query((0, write_data_util_1.mapWriteArgs)(model, operation, args, normalizeRecord));
69
+ return COUNT_OPERATIONS.has(operation)
70
+ ? result
71
+ : (0, write_data_util_1.mapResultRecords)(model, result, stripRecord);
72
+ }
73
+ }
74
+ }
75
+ };
76
+ }
77
+ /**
78
+ * Normalizes the value of a geo field, see `normalizeGeometry`.
79
+ *
80
+ * @throws {SpatialError} `SPATIAL_INVALID_GEOMETRY` for a value that is not a geometry of the field.
81
+ */
82
+ function normalizeValue(modelName, field, value, type) {
83
+ try {
84
+ return (0, common_1.normalizeGeometry)(value, type, spatial_config_1.spatialConfig.MAX_VERTICES);
85
+ }
86
+ catch (error) {
87
+ const reason = error.message;
88
+ throw new common_1.SpatialError(common_1.ErrorCode.SpatialInvalidGeometry, `Invalid geometry of ${modelName}.${field}: ${reason}`, { model: modelName, field, reason });
89
+ }
90
+ }
91
+ /** Whether a value stores a null: `null`, or one of the null sentinels of Prisma. */
92
+ function isNullValue(value) {
93
+ return (value === null ||
94
+ (typeof value === 'object' &&
95
+ /^(Db|Json|Any)Null(Class)?$/.test(value.constructor?.name ?? '')));
96
+ }
97
+ /** The geo fields of a loaded model. */
98
+ function geoFieldsOf(modelName) {
99
+ return internal_1.context.resource.models.get(modelName)?.config.geo;
100
+ }
@@ -0,0 +1,54 @@
1
+ import { LIFECYCLE, OnInit, SpatialCondition, SpatialMatch } from '@appweaver/common';
2
+ import { GeoModel } from './spatial-engine';
3
+ /** The distances in meters of the records matching the `_near` operator of a geo field, by the field and the id. */
4
+ export type SpatialDistances = Map<string, Map<unknown, number>>;
5
+ /** A query filter with its spatial operators resolved. */
6
+ export type ResolvedSpatialFilter = {
7
+ /** The filter, every geo field condition replaced by its database conditions */
8
+ filter: any;
9
+ /** The distances of the `_near` operators of the top level of the filter */
10
+ distances: SpatialDistances;
11
+ };
12
+ /**
13
+ * Resolves the conditions of the geo fields of the query filters into database conditions: `_withinBox` and `_exists`
14
+ * into conditions of the bounding box columns, and `_near`, `_within` and `_intersects` into the ids of the records
15
+ * matched by the `postgis` or the `database` engine of the `spatial.provider` config. It sets up the engine when the
16
+ * application starts.
17
+ */
18
+ export declare class SpatialService implements OnInit {
19
+ static [LIFECYCLE]: boolean;
20
+ /**
21
+ * Sets up the engine for the geo fields of the models, i.e. the triggers of PostGIS.
22
+ *
23
+ * @throws {ConfigurationError} When the engine refuses its setup, i.e. without the PostGIS extension.
24
+ */
25
+ onInit(): Promise<void>;
26
+ /**
27
+ * Returns the geo fields of every model declaring some.
28
+ *
29
+ * @return {GeoModel[]} The models.
30
+ */
31
+ models(): GeoModel[];
32
+ /**
33
+ * Resolves the conditions of the geo fields of a query filter, on its top level, in its logical operators and in
34
+ * the filters of its relations.
35
+ *
36
+ * @param {any} filter - The query filter.
37
+ * @param {string} modelName - The model the filter is matched against.
38
+ * @return {Promise<ResolvedSpatialFilter>} The resolved filter, and the distances of the `_near` matches.
39
+ * @throws {SpatialError} `SPATIAL_INVALID_FILTER` for an invalid operator of a geo field, and
40
+ * `SPATIAL_TOO_MANY_CANDIDATES` when a `_near`, `_within` or `_intersects` operator matches more records than
41
+ * `spatial.maxCandidates`.
42
+ */
43
+ resolveFilter(filter: any, modelName: string): Promise<ResolvedSpatialFilter>;
44
+ /**
45
+ * Finds the records of a model whose geo field matches a spatial condition.
46
+ *
47
+ * @param {string} modelName - The model name.
48
+ * @param {string} field - The geo field.
49
+ * @param {SpatialCondition} condition - The condition.
50
+ * @return {Promise<SpatialMatch[]>} The matches, ordered by their distance for a `near` condition.
51
+ * @throws {SpatialError} `SPATIAL_TOO_MANY_CANDIDATES` when more records than `spatial.maxCandidates` match.
52
+ */
53
+ match(modelName: string, field: string, condition: SpatialCondition): Promise<SpatialMatch[]>;
54
+ }
@@ -0,0 +1,213 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.SpatialService = void 0;
4
+ const common_1 = require("@appweaver/common");
5
+ const core_1 = require("@appweaver/core");
6
+ const internal_1 = require("@appweaver/core/internal");
7
+ const cursor_util_1 = require("../resource/utils/cursor-util");
8
+ const filter_util_1 = require("../resource/utils/filter-util");
9
+ const spatial_config_1 = require("./spatial-config");
10
+ const spatial_engine_1 = require("./spatial-engine");
11
+ const box_util_1 = require("./utils/box-util");
12
+ const logger = (0, common_1.createLogger)('spatial');
13
+ // The operators combining nested filters of the same model
14
+ const LOGICAL_OPERATORS = new Set(['_and', '_or', '_not', '_nor']);
15
+ const QUANTIFIERS = new Set(['_some', '_every', '_none']);
16
+ // The operators a spatial engine matches
17
+ const ENGINE_OPERATORS = new Set(['_near', '_within', '_intersects']);
18
+ /**
19
+ * Resolves the conditions of the geo fields of the query filters into database conditions: `_withinBox` and `_exists`
20
+ * into conditions of the bounding box columns, and `_near`, `_within` and `_intersects` into the ids of the records
21
+ * matched by the `postgis` or the `database` engine of the `spatial.provider` config. It sets up the engine when the
22
+ * application starts.
23
+ */
24
+ class SpatialService {
25
+ static [common_1.LIFECYCLE] = true;
26
+ /** @internal */
27
+ _db = (0, core_1.inject)(common_1.Database);
28
+ /** @internal */
29
+ _engine;
30
+ /** @internal */
31
+ _setup;
32
+ /**
33
+ * Sets up the engine for the geo fields of the models, i.e. the triggers of PostGIS.
34
+ *
35
+ * @throws {ConfigurationError} When the engine refuses its setup, i.e. without the PostGIS extension.
36
+ */
37
+ async onInit() {
38
+ if (!hasGeoModels()) {
39
+ return;
40
+ }
41
+ try {
42
+ await this.ensureSetup();
43
+ }
44
+ catch (error) {
45
+ // An invalid setup fails the start, while an unreachable database is set
46
+ // up again by the next spatial query
47
+ if ((0, common_1.isAppweaverError)(error) && error.module === 'configuration') {
48
+ throw error;
49
+ }
50
+ logger.error(error, 'Cannot set up the spatial engine, retrying on the next use');
51
+ }
52
+ }
53
+ /**
54
+ * Returns the geo fields of every model declaring some.
55
+ *
56
+ * @return {GeoModel[]} The models.
57
+ */
58
+ models() {
59
+ return [...internal_1.context.resource.models.values()]
60
+ .filter((model) => (0, common_1.hasGeo)(model.config))
61
+ .map(geoModelOf);
62
+ }
63
+ /**
64
+ * Resolves the conditions of the geo fields of a query filter, on its top level, in its logical operators and in
65
+ * the filters of its relations.
66
+ *
67
+ * @param {any} filter - The query filter.
68
+ * @param {string} modelName - The model the filter is matched against.
69
+ * @return {Promise<ResolvedSpatialFilter>} The resolved filter, and the distances of the `_near` matches.
70
+ * @throws {SpatialError} `SPATIAL_INVALID_FILTER` for an invalid operator of a geo field, and
71
+ * `SPATIAL_TOO_MANY_CANDIDATES` when a `_near`, `_within` or `_intersects` operator matches more records than
72
+ * `spatial.maxCandidates`.
73
+ */
74
+ async resolveFilter(filter, modelName) {
75
+ const distances = new Map();
76
+ if (!(0, common_1.isPlainObject)(filter) || !hasGeoModels()) {
77
+ return { filter, distances };
78
+ }
79
+ const resolved = await this.resolveLevel(filter, modelName, distances, true);
80
+ return { filter: resolved, distances };
81
+ }
82
+ /**
83
+ * Finds the records of a model whose geo field matches a spatial condition.
84
+ *
85
+ * @param {string} modelName - The model name.
86
+ * @param {string} field - The geo field.
87
+ * @param {SpatialCondition} condition - The condition.
88
+ * @return {Promise<SpatialMatch[]>} The matches, ordered by their distance for a `near` condition.
89
+ * @throws {SpatialError} `SPATIAL_TOO_MANY_CANDIDATES` when more records than `spatial.maxCandidates` match.
90
+ */
91
+ async match(modelName, field, condition) {
92
+ const model = internal_1.context.resource.models.get(modelName);
93
+ if (!model?.config.geo?.[field]) {
94
+ throw new common_1.SpatialError(common_1.ErrorCode.SpatialInvalidFilter, `${modelName}.${field} is not a geo field`, { model: modelName, field, reason: 'not a geo field' });
95
+ }
96
+ await this.ensureSetup();
97
+ const limit = (0, spatial_config_1.spatialMaxCandidates)();
98
+ const matches = await this.engine().match(geoModelOf(model), field, condition, limit);
99
+ if (matches.length > limit) {
100
+ throw new common_1.SpatialError(common_1.ErrorCode.SpatialTooManyCandidates, `The spatial filter of ${modelName}.${field} matches more than ${limit} records, narrow it down`, { model: modelName, field, maxCandidates: limit });
101
+ }
102
+ return matches;
103
+ }
104
+ /** @internal */
105
+ async resolveLevel(filter, modelName, distances, topLevel) {
106
+ if ((0, common_1.isArray)(filter)) {
107
+ return Promise.all(filter.map((item) => this.resolveLevel(item, modelName, distances, false)));
108
+ }
109
+ if (!(0, common_1.isPlainObject)(filter)) {
110
+ return filter;
111
+ }
112
+ const model = internal_1.context.resource.models.get(modelName);
113
+ const geo = model?.config.geo ?? {};
114
+ const resolved = {};
115
+ for (const [key, value] of Object.entries(filter)) {
116
+ if (LOGICAL_OPERATORS.has(key) || QUANTIFIERS.has(key)) {
117
+ resolved[key] = await this.resolveLevel(value, modelName, distances, false);
118
+ }
119
+ else if (geo[key]) {
120
+ resolved[key] = await this.resolveField(modelName, key, value, topLevel ? distances : undefined);
121
+ }
122
+ else {
123
+ const related = relatedModelName(model, key);
124
+ resolved[key] =
125
+ related && ((0, common_1.isPlainObject)(value) || (0, common_1.isArray)(value))
126
+ ? await this.resolveLevel(value, related, distances, false)
127
+ : value;
128
+ }
129
+ }
130
+ return resolved;
131
+ }
132
+ /** The database conditions of the value of a geo field in a filter. @internal */
133
+ async resolveField(modelName, field, value, distances) {
134
+ if (value === null) {
135
+ return new filter_util_1.ResolvedFilterConditions([(0, box_util_1.existsFilter)(field, false)]);
136
+ }
137
+ if (!(0, common_1.isPlainObject)(value)) {
138
+ throw invalidFilter(modelName, field, 'expected an object of the operators _near, _within, _withinBox, _intersects or _exists');
139
+ }
140
+ const conditions = [];
141
+ for (const [operator, operand] of Object.entries(value)) {
142
+ if (operator === '_exists') {
143
+ conditions.push((0, box_util_1.existsFilter)(field, operand !== false && operand !== 'false'));
144
+ continue;
145
+ }
146
+ if (operator !== '_withinBox' && !ENGINE_OPERATORS.has(operator)) {
147
+ throw invalidFilter(modelName, field, `unknown operator ${operator}, expected _near, _within, _withinBox, _intersects or _exists`);
148
+ }
149
+ let condition;
150
+ try {
151
+ if (operator === '_withinBox') {
152
+ conditions.push((0, box_util_1.boxWithinFilter)(field, (0, common_1.normalizeBox)(operand)));
153
+ continue;
154
+ }
155
+ condition = (0, common_1.spatialCondition)(operator, operand, spatial_config_1.spatialConfig.MAX_VERTICES);
156
+ }
157
+ catch (error) {
158
+ throw invalidFilter(modelName, field, error.message);
159
+ }
160
+ const matches = await this.match(modelName, field, condition);
161
+ if (distances && condition.operator === 'near') {
162
+ distances.set(field, new Map(matches.map((match) => [match.id, match.distance])));
163
+ }
164
+ // Fingerprinted as the operator, so a cursor outlives a change of the
165
+ // records it matches
166
+ const ids = (0, cursor_util_1.fingerprintAs)(matches.map((match) => match.id), { [field]: { [operator]: operand } });
167
+ conditions.push({ id: { in: ids } });
168
+ }
169
+ return new filter_util_1.ResolvedFilterConditions(conditions);
170
+ }
171
+ /** @internal */
172
+ engine() {
173
+ this._engine ??=
174
+ (0, spatial_config_1.spatialProvider)() === 'postgis'
175
+ ? new spatial_engine_1.PostgisSpatialEngine(this._db)
176
+ : new spatial_engine_1.DatabaseSpatialEngine(this._db);
177
+ return this._engine;
178
+ }
179
+ /** Sets up the engine once, again on the next call after a failure. @internal */
180
+ ensureSetup() {
181
+ this._setup ??= this.engine()
182
+ .setup(this.models())
183
+ .catch((error) => {
184
+ this._setup = undefined;
185
+ throw error;
186
+ });
187
+ return this._setup;
188
+ }
189
+ }
190
+ exports.SpatialService = SpatialService;
191
+ /** Whether a loaded model declares geo fields. */
192
+ function hasGeoModels() {
193
+ return [...internal_1.context.resource.models.values()].some((model) => (0, common_1.hasGeo)(model.config));
194
+ }
195
+ /** The geo fields of a model and its table. */
196
+ function geoModelOf(model) {
197
+ return {
198
+ name: model.name,
199
+ table: model.config.tableName ?? model.name,
200
+ fields: { ...model.config.geo }
201
+ };
202
+ }
203
+ /** The related model of a relation or a file field of a model. */
204
+ function relatedModelName(model, field) {
205
+ const relation = model?.config.relations?.[field];
206
+ if (relation) {
207
+ return (0, common_1.capitalize)(relation.model);
208
+ }
209
+ return model?.config.files?.[field] ? 'File' : undefined;
210
+ }
211
+ function invalidFilter(modelName, field, reason) {
212
+ return new common_1.SpatialError(common_1.ErrorCode.SpatialInvalidFilter, `Invalid spatial filter of ${modelName}.${field}: ${reason}`, { model: modelName, field, reason });
213
+ }
@@ -0,0 +1,31 @@
1
+ import { GeoBox } from '@appweaver/common';
2
+ /**
3
+ * The condition of the bounding box columns of the geometries covered by one of the boxes, which is exact: a
4
+ * geometry lies in a box when its own box does. The upper bounds of the minimums repeat the ones of the maximums,
5
+ * for the index on the minimums.
6
+ *
7
+ * @param {string} field - The geo field.
8
+ * @param {GeoBox[]} boxes - The boxes.
9
+ * @return {Object} The Prisma condition.
10
+ */
11
+ export declare function boxWithinFilter(field: string, boxes: GeoBox[]): Record<string, any>;
12
+ /**
13
+ * The condition of the bounding box columns of the geometries whose box overlaps one of the boxes, the only ones
14
+ * that can share a point with it.
15
+ *
16
+ * @param {string} field - The geo field.
17
+ * @param {GeoBox[]} boxes - The boxes.
18
+ * @param {boolean} [point=false] - Whether the field holds points, whose minimums equal their maximums, so the
19
+ * index on the minimums bounds both sides.
20
+ * @return {Object} The Prisma condition.
21
+ */
22
+ export declare function boxOverlapFilter(field: string, boxes: GeoBox[], point?: boolean): Record<string, any>;
23
+ /**
24
+ * The condition of the records with a value of a geo field, or without one. The bounding box columns are null
25
+ * exactly when the geometry is, whichever null its JSON column holds.
26
+ *
27
+ * @param {string} field - The geo field.
28
+ * @param {boolean} exists - Whether the records have a value.
29
+ * @return {Object} The Prisma condition.
30
+ */
31
+ export declare function existsFilter(field: string, exists: boolean): Record<string, any>;