@appweaver/data 2.5.0 → 2.6.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 (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
@@ -6,6 +6,7 @@ const common_1 = require("@appweaver/common");
6
6
  const internal_1 = require("@appweaver/core/internal");
7
7
  const core_1 = require("@appweaver/core");
8
8
  const model_schema_1 = require("../resource/model-schema");
9
+ const geo_schema_1 = require("../spatial/geo-schema");
9
10
  const logger = (0, common_1.createLogger)('resource');
10
11
  /**
11
12
  * Creates a resource model from its configuration and defines it in the application context. The names of the
@@ -19,6 +20,7 @@ const logger = (0, common_1.createLogger)('resource');
19
20
  function createModel(modelConfig, override = false) {
20
21
  const config = normalizeRelations(modelConfig);
21
22
  validateSeries(config);
23
+ validateGeo(config);
22
24
  const resourceModel = buildModel(config);
23
25
  logger.debug({ modelName: resourceModel.name }, 'Created resource model');
24
26
  (0, core_1.define)(resourceModel, undefined, override ? 'override' : undefined);
@@ -90,6 +92,62 @@ function validateSeries(config) {
90
92
  throw new common_1.ConfigurationError(common_1.ErrorCode.ConfigurationInvalid, `Series option '${config.name}.ingest' is '${options.ingest}', not one of ${SERIES_INGESTS.join(', ')}`);
91
93
  }
92
94
  }
95
+ /**
96
+ * Checks the geo fields of a model: their types, and names taken by no other field of the model, nor by the columns
97
+ * the field keeps beside its own (`<field>MinLng`, `<field>Geom`, ...) and its distance (`<field>Distance`).
98
+ *
99
+ * @throws {ConfigurationError} For a geo field with an unknown type or a name taken by another field.
100
+ */
101
+ function validateGeo(config) {
102
+ const taken = new Set([
103
+ 'id',
104
+ ...Object.keys(config.scalars ?? {}),
105
+ ...Object.keys(config.relations ?? {}),
106
+ ...Object.keys(config.files ?? {}),
107
+ ...Object.keys(config.virtual ?? {})
108
+ ]);
109
+ const geoFields = Object.keys(config.geo ?? {});
110
+ for (const [field, geo] of Object.entries(config.geo ?? {})) {
111
+ if (!common_1.GEO_FIELD_GEOMETRIES[geo?.type]) {
112
+ throw new common_1.ConfigurationError(common_1.ErrorCode.ConfigurationInvalid, `Geo field '${config.name}.${field}' has the type '${geo?.type}', not one of ${Object.keys(common_1.GEO_FIELD_GEOMETRIES).join(', ')}`);
113
+ }
114
+ const names = [
115
+ field,
116
+ ...Object.values((0, common_1.geoColumns)(field)),
117
+ (0, common_1.distanceFieldName)(field)
118
+ ];
119
+ const conflict = names.find((name) => taken.has(name) || (name !== field && geoFields.includes(name)));
120
+ if (conflict || !/^[A-Za-z]\w*$/.test(field)) {
121
+ throw new common_1.ConfigurationError(common_1.ErrorCode.ConfigurationInvalid, `Geo field '${config.name}.${field}' must be an identifier taken by no other field` +
122
+ (conflict ? `, but '${conflict}' is another field of the model` : ''));
123
+ }
124
+ }
125
+ }
126
+ /**
127
+ * The geo fields of a model, as their input values, or as their output ones, each field followed by its distance from
128
+ * the point of its `_near` filter, which a query filtering by it returns.
129
+ */
130
+ function buildGeoSchema(geo = {}, input = false) {
131
+ const properties = {};
132
+ for (const [name, field] of Object.entries(geo)) {
133
+ properties[name] = (0, geo_schema_1.geoFieldSchema)(field, input);
134
+ if (!input && !field.hidden) {
135
+ properties[(0, common_1.distanceFieldName)(name)] = typebox_1.Type.Optional(typebox_1.Type.Number({
136
+ minimum: 0,
137
+ description: `Distance of ${name} in meters from the point of its _near filter`
138
+ }));
139
+ }
140
+ }
141
+ return typebox_1.Type.Object(properties);
142
+ }
143
+ /** The read restrictions of a model, the distance of a geo field left out or picked with its field. */
144
+ function readOperationConfig(config) {
145
+ const withDistances = (fields) => fields?.flatMap((field) => config.geo?.[field] ? [field, (0, common_1.distanceFieldName)(field)] : [field]);
146
+ return (config.read && {
147
+ omit: withDistances(config.read.omit),
148
+ pick: withDistances(config.read.pick)
149
+ });
150
+ }
93
151
  /** The values of the series fields, each optional and nullable, a null leaving the stored value unchanged. */
94
152
  function buildSeriesModel(series) {
95
153
  const properties = {};
@@ -117,9 +175,12 @@ function buildModel(config) {
117
175
  const virtualSchema = buildScalarsSchema(config?.virtual);
118
176
  const filesSchema = buildFilesSchema(config?.files);
119
177
  const relationsSchema = buildRelationsSchema(config?.relations);
178
+ const geoSchema = buildGeoSchema(config?.geo);
179
+ const geoInputSchema = buildGeoSchema(config?.geo, true);
120
180
  const readModel = typebox_1.Type.Composite([
121
181
  idSchema,
122
182
  scalarsSchema,
183
+ geoSchema,
123
184
  virtualSchema,
124
185
  relationsSchema,
125
186
  filesSchema,
@@ -134,13 +195,23 @@ function buildModel(config) {
134
195
  $id: `${name}Relations`
135
196
  });
136
197
  const filesModel = typebox_1.Type.Composite([filesSchema], { $id: `${name}Files` });
137
- const baseReadModel = omitOrPickScalars(typebox_1.Type.Composite([idSchema, scalarsSchema, virtualSchema, auditSchema]), config.read);
138
- const createModel = omitOrPickScalars(resolveDefaultScalars(typebox_1.Type.Composite([scalarsSchema, virtualSchema]), config), config.create);
139
- const updateModel = omitOrPickScalars(resolveDefaultScalars(typebox_1.Type.Partial(typebox_1.Type.Composite([scalarsSchema, virtualSchema])), config), config.update);
198
+ const baseReadModel = omitOrPickScalars(typebox_1.Type.Composite([
199
+ idSchema,
200
+ scalarsSchema,
201
+ geoSchema,
202
+ virtualSchema,
203
+ auditSchema
204
+ ]), readOperationConfig(config));
205
+ const createModel = omitOrPickScalars(resolveDefaultScalars(typebox_1.Type.Composite([scalarsSchema, geoInputSchema, virtualSchema]), config), config.create);
206
+ const updateModel = omitOrPickScalars(resolveDefaultScalars(typebox_1.Type.Partial(typebox_1.Type.Composite([scalarsSchema, geoInputSchema, virtualSchema])), config), config.update);
140
207
  // The fields of an update, its scalars required the same way as on a
141
208
  // create, since a replacement carries the whole stored state of the
142
209
  // resource. The virtual fields are no part of it, so they stay optional
143
- const replaceModel = omitOrPickScalars(resolveDefaultScalars(typebox_1.Type.Composite([scalarsSchema, typebox_1.Type.Partial(virtualSchema)]), config), config.update);
210
+ const replaceModel = omitOrPickScalars(resolveDefaultScalars(typebox_1.Type.Composite([
211
+ scalarsSchema,
212
+ geoInputSchema,
213
+ typebox_1.Type.Partial(virtualSchema)
214
+ ]), config), config.update);
144
215
  const { readOneModel, readManyModel } = buildOutputModels(baseReadModel, relationsModel, filesModel, config);
145
216
  const readOneNullableModel = buildNullableOutputModel(name);
146
217
  const { createOneModel, updateOneModel, replaceOneModel, relationCreateModel, relationUpdateModel } = buildInputModels(createModel, updateModel, replaceModel, relationsModel, idSchema, config);
@@ -103,6 +103,14 @@ function createService(config, override = false) {
103
103
  }
104
104
  return super.checkAccess(action, resource);
105
105
  }
106
+ async eventAccess(event) {
107
+ const policy = (0, core_1.injectPolicy)(name, false);
108
+ if (policy?.events) {
109
+ const user = (0, core_1.currentAuthUser)() ?? null;
110
+ return policy.events(user, event);
111
+ }
112
+ return super.eventAccess(event);
113
+ }
106
114
  }
107
115
  Object.defineProperty(Service, 'name', {
108
116
  value: `${name}Service`,
package/index.d.ts CHANGED
@@ -7,10 +7,12 @@ export * from './factory/create-service';
7
7
  export * from './resource/model-schema';
8
8
  export * from './resource/resource-loader';
9
9
  export * from './resource/resource-service';
10
+ export { matchesWhere, queryFilterWhere } from './resource/utils/where-util';
10
11
  export * from './resource/schemas';
11
12
  export * from './security/create-auth-resources';
12
13
  export * from './security/helper';
13
14
  export * from './seeder';
15
+ export * from './spatial/spatial-service';
14
16
  export * from './storage/file-service';
15
17
  export * from './timeseries';
16
18
  export * from './types/auth';
package/index.js CHANGED
@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
14
  for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
15
  };
16
16
  Object.defineProperty(exports, "__esModule", { value: true });
17
+ exports.queryFilterWhere = exports.matchesWhere = void 0;
17
18
  __exportStar(require("./config"), exports);
18
19
  __exportStar(require("./database"), exports);
19
20
  __exportStar(require("./export/export-service"), exports);
@@ -23,10 +24,14 @@ __exportStar(require("./factory/create-service"), exports);
23
24
  __exportStar(require("./resource/model-schema"), exports);
24
25
  __exportStar(require("./resource/resource-loader"), exports);
25
26
  __exportStar(require("./resource/resource-service"), exports);
27
+ var where_util_1 = require("./resource/utils/where-util");
28
+ Object.defineProperty(exports, "matchesWhere", { enumerable: true, get: function () { return where_util_1.matchesWhere; } });
29
+ Object.defineProperty(exports, "queryFilterWhere", { enumerable: true, get: function () { return where_util_1.queryFilterWhere; } });
26
30
  __exportStar(require("./resource/schemas"), exports);
27
31
  __exportStar(require("./security/create-auth-resources"), exports);
28
32
  __exportStar(require("./security/helper"), exports);
29
33
  __exportStar(require("./seeder"), exports);
34
+ __exportStar(require("./spatial/spatial-service"), exports);
30
35
  __exportStar(require("./storage/file-service"), exports);
31
36
  __exportStar(require("./timeseries"), exports);
32
37
  __exportStar(require("./types/auth"), exports);
package/internal.d.ts CHANGED
@@ -1,2 +1,4 @@
1
1
  /** The internals of data the CLI builds on, which can change in a minor release. */
2
2
  export { pruneUnusedModels } from './resource/utils/prune-util';
3
+ export { setupDatabase } from './database/setup-database';
4
+ export type { SetupDatabaseParams, SetupDatabaseResult } from './database/setup-database';
package/internal.js CHANGED
@@ -1,6 +1,8 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.pruneUnusedModels = void 0;
3
+ exports.setupDatabase = exports.pruneUnusedModels = void 0;
4
4
  /** The internals of data the CLI builds on, which can change in a minor release. */
5
5
  var prune_util_1 = require("./resource/utils/prune-util");
6
6
  Object.defineProperty(exports, "pruneUnusedModels", { enumerable: true, get: function () { return prune_util_1.pruneUnusedModels; } });
7
+ var setup_database_1 = require("./database/setup-database");
8
+ Object.defineProperty(exports, "setupDatabase", { enumerable: true, get: function () { return setup_database_1.setupDatabase; } });
package/module.js CHANGED
@@ -38,6 +38,7 @@ const database_config_1 = require("./database/database-config");
38
38
  const export_config_1 = require("./export/export-config");
39
39
  const resource_config_1 = require("./resource/resource-config");
40
40
  const auth_config_1 = require("./security/auth-config");
41
+ const spatial_config_1 = require("./spatial/spatial-config");
41
42
  const image_config_1 = require("./storage/image-config");
42
43
  const database_series_config_1 = require("./timeseries/database-series-config");
43
44
  const timescale_config_1 = require("./timeseries/timescale-config");
@@ -55,9 +56,10 @@ exports.default = (0, common_1.defineModule)({
55
56
  auth_config_1.twoFactorModelConfig,
56
57
  auth_config_1.systemConfig,
57
58
  database_series_config_1.databaseSeriesConfig,
58
- timescale_config_1.timescaleConfig
59
+ timescale_config_1.timescaleConfig,
60
+ spatial_config_1.spatialConfig
59
61
  ],
60
- loggers: ['database', 'resource', 'storage', 'timeseries'],
62
+ loggers: ['database', 'resource', 'storage', 'timeseries', 'spatial'],
61
63
  contracts: [
62
64
  { contract: common_1.Database, provider: () => database_config_1.databaseConfig.PROVIDER },
63
65
  { contract: common_1.ImageProcessor, provider: () => image_config_1.imageConfig.PROVIDER }
@@ -92,7 +94,8 @@ exports.default = (0, common_1.defineModule)({
92
94
  load: () => Promise.resolve().then(() => __importStar(require('./storage/file-service'))),
93
95
  requires: [common_1.Database, common_1.Storage]
94
96
  },
95
- { load: () => Promise.resolve().then(() => __importStar(require('./export/export-service'))), requires: [common_1.Database] }
97
+ { load: () => Promise.resolve().then(() => __importStar(require('./export/export-service'))), requires: [common_1.Database] },
98
+ { load: () => Promise.resolve().then(() => __importStar(require('./spatial/spatial-service'))), requires: [common_1.Database] }
96
99
  ],
97
100
  setup: async (context) => (await Promise.resolve().then(() => __importStar(require('./resource/load-data-resources')))).loadDataResources(context),
98
101
  resources: () => Promise.resolve().then(() => __importStar(require('./resources')))
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@appweaver/data",
3
- "version": "2.5.0",
3
+ "version": "2.6.0",
4
4
  "description": "Appweaver - the backend framework for AI-first development (@data)",
5
5
  "author": "Luka Matosevic",
6
6
  "license": "MIT",
@@ -51,8 +51,8 @@
51
51
  "csv-stringify": "6.8.0"
52
52
  },
53
53
  "peerDependencies": {
54
- "@appweaver/common": "^2.5.0",
55
- "@appweaver/core": "^2.5.0",
54
+ "@appweaver/common": "^2.6.0",
55
+ "@appweaver/core": "^2.6.0",
56
56
  "@prisma/client": "^7.9.0"
57
57
  },
58
58
  "devDependencies": {
@@ -1,4 +1,4 @@
1
- import { ActionType, AggregateOptions, AggregateResponse, AggregateSelect, AggregateSelected, BulkItem, IResourceService, QueryFilter, QueryOptions, QueryResponse, QuerySort, Resource, ResourceId, ResourceClient, ResourceData } from '@appweaver/common';
1
+ import { ActionType, AggregateOptions, AggregateResponse, AggregateSelect, AggregateSelected, BulkItem, IResourceService, QueryFilter, QueryOptions, QueryResponse, QuerySort, Resource, ResourceId, ResourceClient, ResourceData, ResourceEvent } from '@appweaver/common';
2
2
  export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Resource, Create = ResourceData<Resource>, Update = Partial<ResourceData<Resource>>, Query = QueryFilter<ReadOne>, Replace = Create> implements IResourceService<ReadOne, ReadMany, Create, Update, Query, Replace> {
3
3
  readonly modelName: string;
4
4
  /**
@@ -44,8 +44,9 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
44
44
  * `_not`, `_nor`), comparison (`_eq`, `_ne`, `_gt`, `_gte`, `_lt`, `_lte`,
45
45
  * `_in`, `_nin`, `_between`, `_like`, `_ilike`, `_starts`, `_ends`,
46
46
  * `_contains`, `_exists`), list (`_has`, `_hasSome`, `_hasEvery`,
47
- * `_isEmpty`), and relation (`_some`, `_every`, `_none`) operators, as well
48
- * as plain field values. Its `searchText` property, if present, is passed to
47
+ * `_isEmpty`), relation (`_some`, `_every`, `_none`), and geo field
48
+ * (`_near`, `_within`, `_withinBox`, `_intersects`) operators, as well as
49
+ * plain field values. Its `searchText` property, if present, is passed to
49
50
  * {@link ResourceService.textSearchQuery} instead of being matched as a
50
51
  * field.
51
52
  * - `page` The one-based page number of results to return, ignored when a
@@ -57,7 +58,8 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
57
58
  * `{ createdAt: 'desc', id: 'asc' }`). Both forms support the fields of the
58
59
  * included to-one relations, given with a dot notation (`author.createdAt`)
59
60
  * or as a nested object (`{ author: { createdAt: 'desc' } }`) (default:
60
- * `-createdAt`).
61
+ * `-createdAt`). A geo field, alone, sorts by the distance from the point
62
+ * of its `_near` filter.
61
63
  * - `cursor` The cursor of the page to return, as issued in the `nextCursor`
62
64
  * or `prevCursor` of an earlier response, which also carries the direction
63
65
  * the page runs in. Takes precedence over `page`.
@@ -65,11 +67,13 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
65
67
  * of every one of them (default: `true`).
66
68
  * @return {Promise<QueryResponse<Object>>} The paged query response containing
67
69
  * the returned resources, the count of the returned items, the cursors of the
68
- * adjacent pages, and the total count unless it was opted out of.
70
+ * adjacent pages, and the total count unless it was opted out of. A resource
71
+ * matched by the `_near` filter of a geo field carries its distance in meters
72
+ * as `<field>Distance`.
69
73
  * @throws {@link ResourceError} `RESOURCE_INVALID_SORT` if the sort input names
70
74
  * a field that cannot be sorted by, `RESOURCE_INVALID_CURSOR` if the cursor
71
- * was issued for another filter or sort order, and a {@link DatabaseError} on
72
- * a database error.
75
+ * was issued for another filter or sort order, a {@link SpatialError} on an
76
+ * invalid geo field filter, and a {@link DatabaseError} on a database error.
73
77
  */
74
78
  query(options?: QueryOptions<ReadMany, Query>): Promise<QueryResponse<ReadMany>>;
75
79
  /**
@@ -292,6 +296,15 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
292
296
  * as {@link ResourceService.delete}.
293
297
  */
294
298
  bulkDelete(ids: ResourceId[]): Promise<ReadOne[]>;
299
+ /**
300
+ * Checks whether the current user may receive a resource event, i.e. on the
301
+ * realtime connection of the user, run as that user with `runAs`. Always
302
+ * granted for the calls run with internal access (see `withoutPolicies`).
303
+ *
304
+ * @param {ResourceEvent} event The action and the resource of the event.
305
+ * @return {Promise<boolean>} True if the user may receive the event.
306
+ */
307
+ checkEventAccess(event: ResourceEvent<ReadOne>): Promise<boolean>;
295
308
  /**
296
309
  * Updates an existing resource the same way as {@link ResourceService.update},
297
310
  * returning the state the resource had before the update along with the
@@ -386,6 +399,18 @@ export declare abstract class ResourceService<ReadOne = Resource, ReadMany = Res
386
399
  * otherwise.
387
400
  */
388
401
  protected checkAccess(action: ActionType, resource: ReadOne): Promise<boolean>;
402
+ /**
403
+ * Checks whether the current user may receive a resource event. By default
404
+ * the user must pass the {@link ResourceService.checkAccess} of a `find` of
405
+ * the resource, which must match the {@link ResourceService.readRestrictions}
406
+ * of the `find`. The restrictions are matched in memory, and by the database
407
+ * when they filter by a relation, so a deleted resource whose restrictions
408
+ * only the database can match is denied.
409
+ *
410
+ * @param {ResourceEvent} event The action and the resource of the event.
411
+ * @return {Promise<boolean>} True if the user may receive the event.
412
+ */
413
+ protected eventAccess(event: ResourceEvent<ReadOne>): Promise<boolean>;
389
414
  /**
390
415
  * Constructs a query object for performing a text search on resources in the
391
416
  * database based on the provided search text. This method will transform the