@itrocks/framework 0.6.8 → 1.0.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.
package/README.md CHANGED
@@ -293,3 +293,32 @@ async function renderProperty(object: any, name: string) {
293
293
  - Build higher‑level tooling (CRUD generators, admin dashboards,
294
294
  documentation tools) on top of the reflection API exposed by the
295
295
  framework.
296
+
297
+ ## SQL relationship adapter
298
+
299
+ The public `@itrocks/framework/sql-relationships` subpath provides reflection/schema bindings for deterministic
300
+ relationship graphs without starting the framework server. Normal bootstrap installs these bindings automatically.
301
+ See [SQL relationship binding](docs/sql-relationships.md) for public hooks, inverse/link mappings and custom schemas.
302
+
303
+ ### SQL projection binding
304
+
305
+ The server bootstrap binds MySQL projection conversion and SQL metadata through the public
306
+ [`@itrocks/framework/sql-projection`](docs/sql-projection.md) subpath. Isolated adapters can use the same binding
307
+ without importing the server bootstrap.
308
+
309
+ ### Authorised property metadata
310
+
311
+ The public [`@itrocks/framework/property-select`](docs/property-select.md) adapter serves authorised reflection
312
+ metadata through real actions. Every routed business class is available without a selector root declaration.
313
+ Supply request-specific path restrictions through [`propertySelectDependsOn`](docs/dependencies.md#property-metadata).
314
+ The browser `property-select-metadata.js` entry provides
315
+ `HttpMetadataProvider`, implementing the selector's neutral metadata port without loading server reflection.
316
+
317
+ ### Selector session composition
318
+
319
+ Bootstrap binds list state transactions to the configured HTTP session store. Each list article receives its router
320
+ identity; selector state and list column settings share durable session coordination while retaining separate
321
+ namespaces.
322
+ The browser obtains authorised root advice before mounting the selector and supplies the list session adapter.
323
+ A stable configured `session.secret` is needed to recognise existing cookies after a server restart.
324
+ See [property selector integration](docs/property-select.md) for route-backed metadata and access.
package/app.d.ts CHANGED
@@ -1,2 +1,4 @@
1
1
  import '@itrocks/auto-redirect/build.js';
2
2
  import '@itrocks/real-viewport-height/real-viewport-height.js';
3
+ import './property-select-list.js';
4
+ export { HttpMetadataProvider } from './property-select-metadata.js';
package/app.js CHANGED
@@ -20,6 +20,7 @@ import { XTargetHistory } from '@itrocks/xtarget/history.js';
20
20
  import { XTargetHoldOn } from '@itrocks/xtarget/hold-on.js';
21
21
  import { XTargetMainTarget } from '@itrocks/xtarget/main-target.js';
22
22
  import { XTargetModifier } from '@itrocks/xtarget/modifier.js';
23
+ import './property-select-list.js';
23
24
  let selector;
24
25
  selector = 'input[data-type=object], ul[data-type=objects] > li > input:not([type=hidden])';
25
26
  build(selector, async (input) => {
@@ -45,3 +46,4 @@ XTargetDefaultOptions({ plugins: [
45
46
  XTargetHistory, XTargetHoldOn, XTargetMainTarget, XTargetModifier, XTargetSecureClick
46
47
  ] });
47
48
  buildXTarget();
49
+ export { HttpMetadataProvider } from './property-select-metadata.js';
@@ -11,15 +11,11 @@ const class_type_2 = require("@itrocks/class-type");
11
11
  const class_view_1 = require("@itrocks/class-view");
12
12
  const class_view_2 = require("@itrocks/class-view");
13
13
  const collection_1 = require("@itrocks/collection");
14
- const composition_1 = require("@itrocks/composition");
15
14
  const config_1 = require("@itrocks/config");
16
15
  const core_transformers_1 = require("@itrocks/core-transformers");
17
16
  const core_transformers_2 = require("@itrocks/core-transformers");
18
- const property_1 = require("@itrocks/decorator/property");
19
17
  const file_1 = require("@itrocks/file");
20
- const lazy_loading_2 = require("@itrocks/lazy-loading");
21
18
  const list_properties_1 = require("@itrocks/list-properties");
22
- const mysql_1 = require("@itrocks/mysql");
23
19
  const password_1 = require("@itrocks/password");
24
20
  const transformers_1 = require("@itrocks/password/transformers");
25
21
  const property_translate_1 = require("@itrocks/property-translate");
@@ -31,12 +27,8 @@ const rename_2 = require("@itrocks/rename");
31
27
  const required_1 = require("@itrocks/required");
32
28
  const route_1 = require("@itrocks/route");
33
29
  const route_2 = require("@itrocks/route");
34
- const sql_build_1 = require("@itrocks/sql-build");
35
- const sql_functions_1 = require("@itrocks/sql-functions");
36
- const sql_join_1 = require("@itrocks/sql-join");
37
30
  const storage_1 = require("@itrocks/storage");
38
31
  const store_1 = require("@itrocks/store");
39
- const store_2 = require("@itrocks/store");
40
32
  const string_formats_1 = require("@itrocks/string-formats");
41
33
  const transformers_3 = require("@itrocks/string-formats/transformers");
42
34
  const template_1 = require("@itrocks/template");
@@ -50,14 +42,8 @@ const date_fns_1 = require("date-fns");
50
42
  const node_path_1 = require("node:path");
51
43
  const node_path_2 = require("node:path");
52
44
  const language_1 = require("./language");
53
- const sql_join_dependencies_1 = require("./sql-join-dependencies");
54
- const sql_join_dependencies_2 = require("./sql-join-dependencies");
55
- const sql_join_dependencies_3 = require("./sql-join-dependencies");
56
- const sql_join_dependencies_4 = require("./sql-join-dependencies");
57
- const sql_join_dependencies_5 = require("./sql-join-dependencies");
58
- const sql_join_dependencies_6 = require("./sql-join-dependencies");
59
- const sql_join_dependencies_7 = require("./sql-join-dependencies");
60
- const sql_join_dependencies_8 = require("./sql-join-dependencies");
45
+ const property_select_1 = require("./property-select");
46
+ const sql_projection_1 = require("./sql-projection");
61
47
  async function propertyOutput(object, property) {
62
48
  return (0, transformer_1.applyTransformer)(await object[property], object, property, transformer_2.HTML, transformer_3.OUTPUT);
63
49
  }
@@ -85,27 +71,8 @@ function bind() {
85
71
  (0, string_formats_1.multilineDependsOn)({
86
72
  setTransformers: transformers_3.setMultilineTransformers
87
73
  });
88
- (0, mysql_1.mysqlDependsOn)({
89
- applyReadTransformer: async function (data, property, object) {
90
- const value = await (0, transformer_1.applyTransformer)(data[property.toString()], object, property, transformer_3.SQL, transformer_3.READ, data);
91
- if ((value !== transformer_2.IGNORE) && Reflect.getOwnMetadata(lazy_loading_2.PROTECT_GET, object, (0, property_1.metadataNameOf)(property))) {
92
- Reflect.deleteMetadata(lazy_loading_2.PROTECT_GET, object, (0, property_1.metadataNameOf)(property));
93
- }
94
- return value;
95
- },
96
- applySaveTransformer: async function (object, property, data) {
97
- const value = Reflect.getMetadata(lazy_loading_2.PROTECT_GET, object, (0, property_1.metadataNameOf)(property))
98
- ? (Object.hasOwn(object, property) ? object[property] : undefined)
99
- : await object[property];
100
- return (0, transformer_1.applyTransformer)(value, object, property, transformer_3.SQL, transformer_3.SAVE, data);
101
- },
102
- columnOf: rename_1.toColumn,
103
- componentOf: composition_1.componentOf,
104
- ignoreTransformedValue: transformer_2.IGNORE,
105
- QueryFunction: sql_functions_1.SqlFunction,
106
- queryFunctionCall: value => [value.value, value.sql],
107
- storeOf: store_2.storeOf
108
- });
74
+ (0, property_select_1.bindPropertySelect)();
75
+ (0, sql_projection_1.bindSqlProjection)();
109
76
  (0, password_1.passwordDependsOn)({
110
77
  setTransformers: transformers_1.setPasswordTransformers
111
78
  });
@@ -115,25 +82,6 @@ function bind() {
115
82
  (0, property_translate_1.propertyTranslateDependsOn)({
116
83
  setTransformers: transformers_2.setPropertyTranslateTransformers
117
84
  });
118
- (0, sql_build_1.sqlBuildDependsOn)({
119
- columnOf: sql_join_dependencies_3.columnOf
120
- });
121
- (0, sql_join_1.sqlJoinDependsOn)({
122
- columnDefinitionOf: sql_join_dependencies_1.columnDefinitionOf,
123
- columnDefinitionsOf: sql_join_dependencies_2.columnDefinitionsOf,
124
- columnOf: sql_join_dependencies_3.columnOf,
125
- componentOf: composition_1.componentOf,
126
- isCollection: sql_join_dependencies_4.isCollection,
127
- isScalar: sql_join_dependencies_5.isScalar,
128
- requiredOf: required_1.requiredOf,
129
- rightColumnDefinitionOf: sql_join_dependencies_6.rightColumnDefinitionOf,
130
- storedAsValueOf: columnDefinition => {
131
- const tableDefinition = (0, sql_join_dependencies_7.tableDefinitionOf)(columnDefinition);
132
- return !!tableDefinition && !(0, store_2.storeOf)(tableDefinition);
133
- },
134
- tableDefinitionOf: sql_join_dependencies_7.tableDefinitionOf,
135
- tableOf: sql_join_dependencies_8.tableOf
136
- });
137
85
  (0, store_1.storeDependsOn)({
138
86
  setTransformers: core_transformers_2.initStoreTransformers,
139
87
  toStoreName: rename_1.toColumn
@@ -0,0 +1,20 @@
1
+ import { Action } from '@itrocks/action';
2
+ import { Request } from '@itrocks/action-request';
3
+ type Operation = 'configuration' | 'context' | 'resolve';
4
+ declare abstract class MetadataAction extends Action {
5
+ protected abstract operation: Operation;
6
+ json(request: Request): Promise<import("@itrocks/core-responses").JsonResponse>;
7
+ }
8
+ export declare class MetadataConfiguration extends MetadataAction {
9
+ protected operation: "configuration";
10
+ }
11
+ export declare class MetadataContext extends MetadataAction {
12
+ protected operation: "context";
13
+ }
14
+ export declare class MetadataResolve extends MetadataAction {
15
+ protected operation: "resolve";
16
+ }
17
+ export declare class PropertySelectTemplate extends Action {
18
+ html(): Promise<import("@itrocks/core-responses").HtmlResponse>;
19
+ }
20
+ export {};
@@ -0,0 +1,53 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.PropertySelectTemplate = exports.MetadataResolve = exports.MetadataContext = exports.MetadataConfiguration = void 0;
4
+ const action_1 = require("@itrocks/action");
5
+ const promises_1 = require("node:fs/promises");
6
+ const property_select_1 = require("./property-select");
7
+ const property_select_2 = require("./property-select");
8
+ const property_select_provider_1 = require("./property-select-provider");
9
+ class MetadataAction extends action_1.Action {
10
+ async json(request) {
11
+ const parameters = request.data;
12
+ const root = parameters.root;
13
+ const path = parameters.path ?? '';
14
+ const headers = { 'Cache-Control': 'no-store' };
15
+ if ((request.request.method !== 'GET') || request.ids.length || typeof root !== 'string' || !root
16
+ || typeof path !== 'string')
17
+ return this.jsonResponse({ error: 'invalid-request' }, 400, headers);
18
+ try {
19
+ const provider = (0, property_select_1.createMetadataProvider)(request, root);
20
+ const result = this.operation === 'configuration' ? await (0, property_select_2.metadataConfiguration)(request, root)
21
+ : await provider[this.operation](root, path);
22
+ return this.jsonResponse(result, 200, headers);
23
+ }
24
+ catch (error) {
25
+ if (error instanceof property_select_provider_1.MetadataError) {
26
+ return this.jsonResponse({ error: error.code }, error.code === 'forbidden' ? 403 : 400, headers);
27
+ }
28
+ if (error instanceof TypeError)
29
+ return this.jsonResponse({ error: 'invalid-path' }, 400, headers);
30
+ throw error;
31
+ }
32
+ }
33
+ }
34
+ class MetadataConfiguration extends MetadataAction {
35
+ operation = 'configuration';
36
+ }
37
+ exports.MetadataConfiguration = MetadataConfiguration;
38
+ class MetadataContext extends MetadataAction {
39
+ operation = 'context';
40
+ }
41
+ exports.MetadataContext = MetadataContext;
42
+ class MetadataResolve extends MetadataAction {
43
+ operation = 'resolve';
44
+ }
45
+ exports.MetadataResolve = MetadataResolve;
46
+ class PropertySelectTemplate extends action_1.Action {
47
+ async html() {
48
+ const template = require.resolve('@itrocks/property-select/front/property-select.html');
49
+ return this.htmlResponse(await (0, promises_1.readFile)(template, 'utf8'));
50
+ }
51
+ }
52
+ exports.PropertySelectTemplate = PropertySelectTemplate;
53
+ //# sourceMappingURL=property-select-actions.js.map
@@ -0,0 +1,23 @@
1
+ import { MetadataProvider } from '@itrocks/property-select';
2
+ import { ObjectContext } from '@itrocks/property-select';
3
+ import { PropertyDescription } from '@itrocks/property-select';
4
+ import { MetadataRoot } from './property-select';
5
+ export type MetadataErrorCode = 'forbidden' | 'invalid-path' | 'ambiguous-type' | 'unknown-target';
6
+ type Authorise = (root: string, path: string) => boolean | Promise<boolean>;
7
+ export declare class MetadataError extends Error {
8
+ readonly code: MetadataErrorCode;
9
+ constructor(code: MetadataErrorCode);
10
+ }
11
+ export declare class ReflectionMetadataProvider implements MetadataProvider {
12
+ private readonly roots;
13
+ private readonly authorise;
14
+ constructor(roots: Readonly<Record<string, MetadataRoot>>, authorise?: Authorise);
15
+ private allowed;
16
+ private check;
17
+ context(root: string, path: string, signal?: AbortSignal): Promise<ObjectContext>;
18
+ private description;
19
+ private names;
20
+ resolve(root: string, path: string, signal?: AbortSignal): Promise<PropertyDescription | ObjectContext>;
21
+ private resolved;
22
+ }
23
+ export {};
@@ -0,0 +1,174 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.ReflectionMetadataProvider = exports.MetadataError = void 0;
4
+ const class_file_1 = require("@itrocks/class-file");
5
+ const class_type_1 = require("@itrocks/class-type");
6
+ const composition_1 = require("@itrocks/composition");
7
+ const composition_2 = require("@itrocks/composition");
8
+ const property_select_1 = require("@itrocks/property-select");
9
+ const route_1 = require("@itrocks/route");
10
+ const node_crypto_1 = require("node:crypto");
11
+ const reflect_class_1 = require("./reflect-class");
12
+ const reflect_property_1 = require("./reflect-property");
13
+ function aborted(signal) {
14
+ signal?.throwIfAborted();
15
+ }
16
+ function relationId(type, name) {
17
+ const context = new reflect_class_1.ReflectClass(type);
18
+ const property = context.propertyTypes[name];
19
+ const parent = context.parent;
20
+ if (parent && Object.hasOwn(parent.propertyTypes, name) && (parent.propertyTypes[name] === property)) {
21
+ return relationId(parent.type, name);
22
+ }
23
+ for (const uses of context.uses) {
24
+ if (new reflect_class_1.ReflectClass(uses).propertyTypes[name] === property)
25
+ return relationId(uses, name);
26
+ }
27
+ return (0, node_crypto_1.createHash)('sha256').update(`${typeId(type)}.${name}`).digest('hex').slice(0, 24);
28
+ }
29
+ function rootType(root) {
30
+ if (typeof root.type !== 'string')
31
+ return root.type;
32
+ const type = (0, route_1.resolveDestination)(root.type);
33
+ if (typeof type !== 'function')
34
+ throw new Error('Metadata root must resolve to a domain class');
35
+ return type;
36
+ }
37
+ function typeId(type) {
38
+ return (0, node_crypto_1.createHash)('sha256').update(`${(0, class_file_1.fileOf)(type)}:${type.name}`).digest('hex').slice(0, 24);
39
+ }
40
+ class MetadataError extends Error {
41
+ code;
42
+ constructor(code) {
43
+ super(code);
44
+ this.code = code;
45
+ this.name = 'MetadataError';
46
+ }
47
+ }
48
+ exports.MetadataError = MetadataError;
49
+ class ReflectionMetadataProvider {
50
+ roots;
51
+ authorise;
52
+ constructor(roots, authorise = () => true) {
53
+ this.roots = roots;
54
+ this.authorise = authorise;
55
+ }
56
+ async allowed(root, path, signal) {
57
+ aborted(signal);
58
+ const configuration = Object.hasOwn(this.roots, root) ? this.roots[root] : undefined;
59
+ if (!configuration)
60
+ return false;
61
+ const paths = configuration.paths;
62
+ if (path && paths && !paths.some(allowed => (allowed === path) || allowed.startsWith(path + '.')))
63
+ return false;
64
+ const result = await this.authorise(root, path);
65
+ aborted(signal);
66
+ return result;
67
+ }
68
+ async check(root, path, signal) {
69
+ const parts = path ? path.split('.') : [];
70
+ for (let depth = 0; depth <= parts.length; depth++) {
71
+ if (!await this.allowed(root, parts.slice(0, depth).join('.'), signal))
72
+ throw new MetadataError('forbidden');
73
+ }
74
+ }
75
+ async context(root, path, signal) {
76
+ path = (0, property_select_1.normalisePath)(path);
77
+ await this.check(root, path, signal);
78
+ const type = rootType(this.roots[root]);
79
+ const resolved = path ? this.resolved(type, path) : undefined;
80
+ if (resolved && !resolved.property.relation && resolved.targetMultiplicity !== 'unknown') {
81
+ throw new MetadataError('invalid-path');
82
+ }
83
+ const target = resolved ? resolved.target : type;
84
+ if (!target)
85
+ throw new MetadataError('unknown-target');
86
+ const context = new reflect_class_1.ReflectClass(target);
87
+ const names = this.names(context);
88
+ const properties = [];
89
+ for (const name of names) {
90
+ const full = path ? `${path}.${name}` : name;
91
+ if (await this.allowed(root, full, signal))
92
+ properties.push(this.description(context, name, full, names));
93
+ }
94
+ aborted(signal);
95
+ const { displayOf: classDisplay } = require('@itrocks/class-view');
96
+ return { label: classDisplay(target) || target.name, path, properties, type: typeId(target) };
97
+ }
98
+ description(context, name, path, names) {
99
+ const { displayOf } = require('@itrocks/property-view');
100
+ const property = new reflect_property_1.ReflectProperty(context, name);
101
+ const fact = property.relation;
102
+ const description = {
103
+ kind: fact ? 'relation' : 'terminal', label: displayOf(context.type, name) || name,
104
+ name, order: names.indexOf(name), path
105
+ };
106
+ if (!fact)
107
+ return description;
108
+ let inverse = fact.inverse;
109
+ let cardinality = fact.cardinality;
110
+ if (fact.target) {
111
+ description.target = typeId(fact.target);
112
+ if (!inverse && ((0, composition_1.componentOf)(context.type, name) || (0, composition_2.compositeOf)(context.type, name))) {
113
+ const opposite = (0, composition_1.componentOf)(context.type, name) ? composition_2.compositeOf : composition_1.componentOf;
114
+ const candidates = Object.keys(new reflect_class_1.ReflectClass(fact.target).propertyTypes).filter(candidate => {
115
+ if (!opposite(fact.target, candidate))
116
+ return false;
117
+ const other = new reflect_property_1.ReflectProperty(fact.target, candidate).relation;
118
+ return other?.target && (0, class_type_1.inherits)(context.type, other.target);
119
+ });
120
+ if (candidates.length === 1) {
121
+ inverse = candidates[0];
122
+ const other = new reflect_property_1.ReflectProperty(fact.target, inverse).relation;
123
+ if (cardinality === 'unknown') {
124
+ const pair = `${fact.targetMultiplicity}/${other.targetMultiplicity}`;
125
+ cardinality = pair === 'many/one' ? 'one-to-many'
126
+ : pair === 'one/many' ? 'many-to-one' : pair === 'one/one' ? 'one-to-one' : 'unknown';
127
+ }
128
+ }
129
+ }
130
+ if (inverse) {
131
+ const name = inverse.startsWith(fact.target.name + '.') ? inverse.slice(fact.target.name.length + 1) : inverse;
132
+ inverse = Object.hasOwn(new reflect_class_1.ReflectClass(fact.target).propertyTypes, name)
133
+ ? relationId(fact.target, name) : inverse;
134
+ }
135
+ }
136
+ description.relation = { cardinality, id: relationId(context.type, name), ...(inverse ? { inverse } : {}) };
137
+ return description;
138
+ }
139
+ names(context) {
140
+ const { ReflectClass: ComposedClass } = require('@itrocks/reflect');
141
+ if (!(new ComposedClass(context.type) instanceof reflect_class_1.ReflectClass)) {
142
+ throw new Error('Metadata requires framework reflection composition before use');
143
+ }
144
+ const known = Object.keys(context.propertyTypes);
145
+ // Composed framework reflection enumerates types, so display defaults never construct domain records.
146
+ const { displayOrderOf } = require('@itrocks/property-view');
147
+ const order = displayOrderOf(context.type).map(String);
148
+ return [...new Set([...order.filter(name => known.includes(name)), ...known.sort()])];
149
+ }
150
+ async resolve(root, path, signal) {
151
+ path = (0, property_select_1.normalisePath)(path);
152
+ if (!path)
153
+ return this.context(root, path, signal);
154
+ await this.check(root, path, signal);
155
+ const resolved = this.resolved(rootType(this.roots[root]), path);
156
+ const context = new reflect_class_1.ReflectClass(resolved.property.class.type);
157
+ aborted(signal);
158
+ return this.description(context, String(resolved.property.name), path, this.names(context));
159
+ }
160
+ resolved(type, path) {
161
+ const reflection = require('@itrocks/reflect-path');
162
+ const { PropertyPathError, resolvePropertyPath } = reflection;
163
+ try {
164
+ return resolvePropertyPath(new reflect_class_1.ReflectClass(type), path);
165
+ }
166
+ catch (error) {
167
+ if (!(error instanceof PropertyPathError))
168
+ throw error;
169
+ throw new MetadataError(error.code === 'terminal-traversal' ? 'invalid-path' : error.code);
170
+ }
171
+ }
172
+ }
173
+ exports.ReflectionMetadataProvider = ReflectionMetadataProvider;
174
+ //# sourceMappingURL=property-select-provider.js.map
@@ -0,0 +1,24 @@
1
+ import { Request } from '@itrocks/action-request';
2
+ import { Type } from '@itrocks/class-type';
3
+ import { RootId } from '@itrocks/property-select';
4
+ import { ReflectionMetadataProvider } from './property-select-provider';
5
+ export type MetadataRoot = {
6
+ advice?: readonly string[];
7
+ paths?: readonly string[];
8
+ type: Type | string;
9
+ version?: string;
10
+ };
11
+ export type PropertySelectDependencies = {
12
+ advice: (request: Request, root: RootId) => readonly string[] | Promise<readonly string[]>;
13
+ authorise: (request: Request, root: RootId, path: string) => boolean | Promise<boolean>;
14
+ };
15
+ export { MetadataError } from './property-select-provider';
16
+ export type { MetadataErrorCode } from './property-select-provider';
17
+ export { ReflectionMetadataProvider } from './property-select-provider';
18
+ export declare function bindPropertySelect(): void;
19
+ export declare function createMetadataProvider(request: Request, root?: RootId): ReflectionMetadataProvider;
20
+ export declare function metadataConfiguration(request: Request, root: RootId): Promise<{
21
+ advice: readonly string[];
22
+ version: string;
23
+ }>;
24
+ export declare function propertySelectDependsOn(overrides: Partial<PropertySelectDependencies>): void;
@@ -0,0 +1,74 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.ReflectionMetadataProvider = exports.MetadataError = void 0;
4
+ exports.bindPropertySelect = bindPropertySelect;
5
+ exports.createMetadataProvider = createMetadataProvider;
6
+ exports.metadataConfiguration = metadataConfiguration;
7
+ exports.propertySelectDependsOn = propertySelectDependsOn;
8
+ const action_1 = require("@itrocks/action");
9
+ const class_type_1 = require("@itrocks/class-type");
10
+ const class_type_2 = require("@itrocks/class-type");
11
+ const fastify_1 = require("@itrocks/fastify");
12
+ const list_1 = require("@itrocks/list");
13
+ const selector_state_1 = require("@itrocks/list/selector-state");
14
+ const property_select_1 = require("@itrocks/property-select");
15
+ const route_1 = require("@itrocks/route");
16
+ const property_select_provider_1 = require("./property-select-provider");
17
+ const property_select_provider_2 = require("./property-select-provider");
18
+ const dependencies = { advice: () => [], authorise: () => true };
19
+ function routeType(root) {
20
+ if (!root.startsWith('/'))
21
+ return;
22
+ const type = route_1.routes.resolve(root);
23
+ return (0, class_type_2.isAnyType)(type) && type !== action_1.Action && !(type.prototype instanceof action_1.Action) ? type : undefined;
24
+ }
25
+ var property_select_provider_3 = require("./property-select-provider");
26
+ Object.defineProperty(exports, "MetadataError", { enumerable: true, get: function () { return property_select_provider_3.MetadataError; } });
27
+ var property_select_provider_4 = require("./property-select-provider");
28
+ Object.defineProperty(exports, "ReflectionMetadataProvider", { enumerable: true, get: function () { return property_select_provider_4.ReflectionMetadataProvider; } });
29
+ function bindPropertySelect() {
30
+ (0, selector_state_1.listStateDependsOn)({ transaction: fastify_1.sessionTransaction });
31
+ (0, list_1.listDependsOn)({ access: async (request) => {
32
+ const root = request.route;
33
+ const type = routeType(root);
34
+ if (!type || (0, class_type_1.baseType)(type) !== (0, class_type_1.baseType)(request.type))
35
+ return { authorise: async () => { } };
36
+ const provider = createMetadataProvider(request, root);
37
+ await provider.context(root, '');
38
+ return { authorise: async (path) => { await provider.resolve(root, path); }, root };
39
+ } });
40
+ // Loaded after composition; action classes never trigger the framework bootstrap.
41
+ route_1.routes.add('/property-select/template', '@itrocks/framework/property-select-actions:PropertySelectTemplate');
42
+ route_1.routes.add('/property-select/configuration', '@itrocks/framework/property-select-actions:MetadataConfiguration');
43
+ route_1.routes.add('/property-select/context', '@itrocks/framework/property-select-actions:MetadataContext');
44
+ route_1.routes.add('/property-select/resolve', '@itrocks/framework/property-select-actions:MetadataResolve');
45
+ }
46
+ function createMetadataProvider(request, root = request.route) {
47
+ const type = routeType(root);
48
+ const roots = type ? { [root]: { type } } : {};
49
+ return new property_select_provider_2.ReflectionMetadataProvider(roots, (root, path) => dependencies.authorise(request, root, path));
50
+ }
51
+ async function metadataConfiguration(request, root) {
52
+ const provider = createMetadataProvider(request, root);
53
+ await provider.context(root, '');
54
+ const advice = [];
55
+ for (const path of await dependencies.advice(request, root)) {
56
+ try {
57
+ const canonical = (0, property_select_1.normalisePath)(path);
58
+ if (!canonical)
59
+ continue;
60
+ const description = await provider.resolve(root, canonical);
61
+ if (!('properties' in description) && (description.kind === 'relation'))
62
+ advice.push(canonical);
63
+ }
64
+ catch (error) {
65
+ if (!(error instanceof property_select_provider_1.MetadataError) && !(error instanceof TypeError))
66
+ throw error;
67
+ }
68
+ }
69
+ return { advice: [...new Set(advice)], version: '1' };
70
+ }
71
+ function propertySelectDependsOn(overrides) {
72
+ Object.assign(dependencies, overrides);
73
+ }
74
+ //# sourceMappingURL=property-select.js.map
@@ -6,5 +6,6 @@ export declare class ReflectClass<T extends object = object> extends RC<T> {
6
6
  get parent(): ReflectClass | null;
7
7
  get properties(): ReflectProperty<T, keyof T>[];
8
8
  get property(): { [K in keyof T]: ReflectProperty<T, K>; };
9
+ get propertyNames(): Array<keyof T>;
9
10
  get uses(): import("@itrocks/class-type").Type[];
10
11
  }
@@ -33,6 +33,18 @@ class ReflectClass extends reflect_1.ReflectClass {
33
33
  Object.defineProperty(this, 'property', { configurable: true, enumerable: false, value: properties, writable: true });
34
34
  return properties;
35
35
  }
36
+ get propertyNames() {
37
+ const names = new Set(Object.keys(this.propertyTypes));
38
+ let prototype = this.type.prototype;
39
+ while (prototype && prototype !== Object.prototype) {
40
+ for (const [name, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(prototype))) {
41
+ if (descriptor.get && !name.startsWith('_'))
42
+ names.add(name);
43
+ }
44
+ prototype = Object.getPrototypeOf(prototype);
45
+ }
46
+ return [...names].sort();
47
+ }
36
48
  get uses() {
37
49
  const value = (0, uses_1.usesOf)(this.type);
38
50
  Object.defineProperty(this, 'uses', { configurable: true, enumerable: false, value, writable: true });
@@ -9,17 +9,20 @@ exports.rightColumnDefinitionOf = rightColumnDefinitionOf;
9
9
  exports.tableDefinitionOf = tableDefinitionOf;
10
10
  exports.tableOf = tableOf;
11
11
  const class_type_1 = require("@itrocks/class-type");
12
- const class_type_2 = require("@itrocks/class-type");
13
12
  const composition_1 = require("@itrocks/composition");
14
13
  const property_type_1 = require("@itrocks/property-type");
15
14
  const rename_1 = require("@itrocks/rename");
15
+ const sql_join_1 = require("@itrocks/sql-join");
16
16
  const store_1 = require("@itrocks/store");
17
17
  const reflect_class_1 = require("./reflect-class");
18
+ const reflect_property_1 = require("./reflect-property");
18
19
  function columnDefinitionOf(tableDefinition, column) {
19
- return columnDefinitionsOf(tableDefinition)[column];
20
+ const definitions = columnDefinitionsOf(tableDefinition);
21
+ return Object.hasOwn(definitions, column) ? definitions[column] : undefined;
20
22
  }
21
23
  function columnDefinitionsOf(tableDefinition) {
22
- return new reflect_class_1.ReflectClass(tableDefinition).property;
24
+ const context = new reflect_class_1.ReflectClass(tableDefinition);
25
+ return Object.fromEntries(Object.keys(context.propertyTypes).map(name => [name, new reflect_property_1.ReflectProperty(context, name)]));
23
26
  }
24
27
  function columnOf(columnDefinition) {
25
28
  const tableDefinition = tableDefinitionOf(columnDefinition);
@@ -29,28 +32,41 @@ function columnOf(columnDefinition) {
29
32
  return (0, rename_1.toColumn)(property);
30
33
  }
31
34
  function isCollection(columnDefinition) {
32
- return columnDefinition.type instanceof property_type_1.CollectionType;
35
+ return columnDefinition.relation?.targetMultiplicity === 'many';
33
36
  }
34
37
  function isScalar(columnDefinition) {
35
- return tableDefinitionOf(columnDefinition) === undefined;
38
+ const relation = columnDefinition.relation;
39
+ if (relation || (columnDefinition.type instanceof property_type_1.UnknownType)) {
40
+ tableDefinitionOf(columnDefinition);
41
+ return false;
42
+ }
43
+ return true;
36
44
  }
37
45
  function rightColumnDefinitionOf(columnDefinition) {
38
46
  const leftTableDefinition = columnDefinition.class.type;
39
47
  const rightTableDefinition = tableDefinitionOf(columnDefinition);
40
48
  if (!rightTableDefinition)
41
49
  return;
42
- for (const candidate of new reflect_class_1.ReflectClass(rightTableDefinition).properties) {
50
+ const candidates = Object.values(columnDefinitionsOf(rightTableDefinition)).filter(candidate => {
43
51
  if (!(0, composition_1.compositeOf)(rightTableDefinition, candidate.name))
44
- continue;
45
- const candidateTableDefinition = tableDefinitionOf(candidate);
46
- if (candidateTableDefinition && (0, class_type_1.inherits)(leftTableDefinition, candidateTableDefinition))
47
- return candidate;
52
+ return false;
53
+ const candidateType = tableDefinitionOf(candidate);
54
+ return candidateType && (0, class_type_1.inherits)(leftTableDefinition, candidateType);
55
+ });
56
+ if (candidates.length > 1) {
57
+ throw new sql_join_1.RelationshipError('unsupported-relationship', String(columnDefinition.name));
48
58
  }
59
+ return candidates[0];
49
60
  }
50
61
  function tableDefinitionOf(columnDefinition) {
51
- const propertyType = columnDefinition.type;
52
- const type = (propertyType instanceof property_type_1.CollectionType) ? propertyType.elementType.lead : propertyType.lead;
53
- return (0, class_type_2.isAnyType)(type) ? type : undefined;
62
+ const relation = columnDefinition.relation;
63
+ if (relation && !relation.target) {
64
+ throw new sql_join_1.RelationshipError(relation.targets.length ? 'ambiguous-type' : 'unsupported-relationship', String(columnDefinition.name));
65
+ }
66
+ if (columnDefinition.type instanceof property_type_1.UnknownType) {
67
+ throw new sql_join_1.RelationshipError('unsupported-relationship', String(columnDefinition.name));
68
+ }
69
+ return relation?.target;
54
70
  }
55
71
  function tableOf(tableDefinition) {
56
72
  const table = (0, store_1.storeOf)(tableDefinition);
@@ -0,0 +1 @@
1
+ export declare function bindSqlProjection(): void;
@@ -0,0 +1,44 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.bindSqlProjection = bindSqlProjection;
4
+ const composition_1 = require("@itrocks/composition");
5
+ const property_1 = require("@itrocks/decorator/property");
6
+ const lazy_loading_1 = require("@itrocks/lazy-loading");
7
+ const mysql_1 = require("@itrocks/mysql");
8
+ const rename_1 = require("@itrocks/rename");
9
+ const sql_build_1 = require("@itrocks/sql-build");
10
+ const sql_functions_1 = require("@itrocks/sql-functions");
11
+ const store_1 = require("@itrocks/store");
12
+ const transformer_1 = require("@itrocks/transformer");
13
+ const transformer_2 = require("@itrocks/transformer");
14
+ const transformer_3 = require("@itrocks/transformer");
15
+ const transformer_4 = require("@itrocks/transformer");
16
+ const transformer_5 = require("@itrocks/transformer");
17
+ const sql_join_dependencies_1 = require("./sql-join-dependencies");
18
+ const sql_relationships_1 = require("./sql-relationships");
19
+ function bindSqlProjection() {
20
+ (0, mysql_1.mysqlDependsOn)({
21
+ applyReadTransformer: async function (data, property, object) {
22
+ const value = await (0, transformer_1.applyTransformer)(data[property.toString()], object, property, transformer_5.SQL, transformer_3.READ, data);
23
+ if ((value !== transformer_2.IGNORE) && Reflect.getOwnMetadata(lazy_loading_1.PROTECT_GET, object, (0, property_1.metadataNameOf)(property))) {
24
+ Reflect.deleteMetadata(lazy_loading_1.PROTECT_GET, object, (0, property_1.metadataNameOf)(property));
25
+ }
26
+ return value;
27
+ },
28
+ applySaveTransformer: async function (object, property, data) {
29
+ const value = Reflect.getMetadata(lazy_loading_1.PROTECT_GET, object, (0, property_1.metadataNameOf)(property))
30
+ ? (Object.hasOwn(object, property) ? object[property] : undefined)
31
+ : await object[property];
32
+ return (0, transformer_1.applyTransformer)(value, object, property, transformer_5.SQL, transformer_4.SAVE, data);
33
+ },
34
+ columnOf: rename_1.toColumn,
35
+ componentOf: composition_1.componentOf,
36
+ ignoreTransformedValue: transformer_2.IGNORE,
37
+ QueryFunction: sql_functions_1.SqlFunction,
38
+ queryFunctionCall: value => [value.value, value.sql],
39
+ storeOf: store_1.storeOf
40
+ });
41
+ (0, sql_build_1.sqlBuildDependsOn)({ columnOf: sql_join_dependencies_1.columnOf });
42
+ (0, sql_relationships_1.bindSqlJoins)();
43
+ }
44
+ //# sourceMappingURL=sql-projection.js.map
@@ -0,0 +1,11 @@
1
+ import { Relationship } from '@itrocks/sql-join';
2
+ import { RelationshipMapping } from '@itrocks/sql-join';
3
+ import { ColumnDefinition } from './sql-join-dependencies';
4
+ import { TableDefinition } from './sql-join-dependencies';
5
+ export type SqlRelationshipDependencies = {
6
+ mappingOf: (property: ColumnDefinition) => RelationshipMapping | undefined;
7
+ };
8
+ export type { ColumnDefinition, TableDefinition } from './sql-join-dependencies';
9
+ export declare function bindSqlJoins(): void;
10
+ export declare function relationshipOf(table: TableDefinition, column: string, property: ColumnDefinition): Relationship;
11
+ export declare function sqlRelationshipsDependsOn(overrides: Partial<SqlRelationshipDependencies>): void;
@@ -0,0 +1,126 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.bindSqlJoins = bindSqlJoins;
4
+ exports.relationshipOf = relationshipOf;
5
+ exports.sqlRelationshipsDependsOn = sqlRelationshipsDependsOn;
6
+ const class_type_1 = require("@itrocks/class-type");
7
+ const composition_1 = require("@itrocks/composition");
8
+ const composition_2 = require("@itrocks/composition");
9
+ const mysql_1 = require("@itrocks/mysql");
10
+ const reflect_path_1 = require("@itrocks/reflect-path");
11
+ const reflect_path_2 = require("@itrocks/reflect-path");
12
+ const rename_1 = require("@itrocks/rename");
13
+ const required_1 = require("@itrocks/required");
14
+ const sql_join_1 = require("@itrocks/sql-join");
15
+ const sql_join_2 = require("@itrocks/sql-join");
16
+ const store_1 = require("@itrocks/store");
17
+ const sql_join_dependencies_1 = require("./sql-join-dependencies");
18
+ const sql_join_dependencies_2 = require("./sql-join-dependencies");
19
+ const sql_join_dependencies_3 = require("./sql-join-dependencies");
20
+ const sql_join_dependencies_4 = require("./sql-join-dependencies");
21
+ const sql_join_dependencies_5 = require("./sql-join-dependencies");
22
+ const sql_join_dependencies_6 = require("./sql-join-dependencies");
23
+ const sql_join_dependencies_7 = require("./sql-join-dependencies");
24
+ const sql_join_dependencies_8 = require("./sql-join-dependencies");
25
+ const dependencies = { mappingOf: () => undefined };
26
+ function bindSqlJoins() {
27
+ (0, sql_join_2.sqlJoinDependsOn)({
28
+ columnDefinitionOf: sql_join_dependencies_1.columnDefinitionOf, columnDefinitionsOf: sql_join_dependencies_2.columnDefinitionsOf, columnOf: sql_join_dependencies_3.columnOf, componentOf: composition_1.componentOf, isCollection: sql_join_dependencies_4.isCollection, isScalar: sql_join_dependencies_5.isScalar,
29
+ multiplicityOf: property => {
30
+ try {
31
+ return (0, reflect_path_2.resolvePropertyPath)(property.class, [String(property.name)]).targetMultiplicity;
32
+ }
33
+ catch (error) {
34
+ if (!(error instanceof reflect_path_1.PropertyPathError))
35
+ throw error;
36
+ throw new sql_join_1.RelationshipError(error.code === 'ambiguous-type' ? 'ambiguous-type'
37
+ : error.code === 'invalid-path' ? 'invalid-path' : 'unsupported-relationship', error.path);
38
+ }
39
+ },
40
+ relationshipOf, requiredOf: required_1.requiredOf, rightColumnDefinitionOf: sql_join_dependencies_6.rightColumnDefinitionOf,
41
+ storedAsValueOf: property => {
42
+ const target = (0, sql_join_dependencies_7.tableDefinitionOf)(property);
43
+ return !!target && !(0, store_1.storeOf)(target);
44
+ },
45
+ tableDefinitionOf: sql_join_dependencies_7.tableDefinitionOf, tableOf: sql_join_dependencies_8.tableOf
46
+ });
47
+ }
48
+ function relationshipOf(table, column, property) {
49
+ const fact = property.relation;
50
+ const target = (0, sql_join_dependencies_7.tableDefinitionOf)(property);
51
+ if (!fact || !target)
52
+ throw new sql_join_1.RelationshipError('unsupported-relationship', column);
53
+ const multiplicity = fact.targetMultiplicity;
54
+ if (((multiplicity === 'many') && ['many-to-one', 'one-to-one'].includes(fact.cardinality))
55
+ || ((multiplicity === 'one') && ['one-to-many', 'many-to-many'].includes(fact.cardinality))) {
56
+ throw new sql_join_1.RelationshipError('unsupported-relationship', column);
57
+ }
58
+ let mapping = dependencies.mappingOf(property);
59
+ let inverse;
60
+ if (!mapping && fact.inverse) {
61
+ // A qualified identity is explicit; arbitrary catalogue ids require a schema mapping.
62
+ const prefix = `${target.name}.`;
63
+ const name = fact.inverse.startsWith(prefix) ? fact.inverse.slice(prefix.length) : fact.inverse;
64
+ inverse = (0, sql_join_dependencies_1.columnDefinitionOf)(target, name);
65
+ const inverseTarget = inverse && (0, sql_join_dependencies_7.tableDefinitionOf)(inverse);
66
+ if (!inverse || !inverseTarget || !(0, class_type_1.inherits)(table, inverseTarget)) {
67
+ throw new sql_join_1.RelationshipError('unsupported-relationship', column);
68
+ }
69
+ }
70
+ if (!mapping && !inverse && (0, composition_2.compositeOf)(table, column)) {
71
+ const candidates = Object.values((0, sql_join_dependencies_2.columnDefinitionsOf)(target)).filter(candidate => {
72
+ if (!(0, composition_1.componentOf)(target, candidate.name))
73
+ return false;
74
+ const candidateTarget = (0, sql_join_dependencies_7.tableDefinitionOf)(candidate);
75
+ return candidateTarget && (0, class_type_1.inherits)(table, candidateTarget);
76
+ });
77
+ if (candidates.length > 1)
78
+ throw new sql_join_1.RelationshipError('unsupported-relationship', column);
79
+ inverse = candidates[0];
80
+ }
81
+ if (!mapping && (fact.cardinality === 'many-to-many')) {
82
+ const left = (0, sql_join_dependencies_8.tableOf)(table);
83
+ const right = (0, sql_join_dependencies_8.tableOf)(target);
84
+ if ((left === right) || ((0, rename_1.toColumn)(left) === (0, rename_1.toColumn)(right))) {
85
+ throw new sql_join_1.RelationshipError('unsupported-relationship', column);
86
+ }
87
+ mapping = {
88
+ leftColumn: 'id', rightColumn: 'id',
89
+ through: { leftColumn: (0, rename_1.toColumn)(left) + '_id', rightColumn: (0, rename_1.toColumn)(right) + '_id',
90
+ table: (0, mysql_1.joinTableName)(left, right) }
91
+ };
92
+ }
93
+ if (!mapping) {
94
+ const component = (0, composition_1.componentOf)(table, column);
95
+ if ((multiplicity === 'many') || component) {
96
+ inverse ??= (0, sql_join_dependencies_6.rightColumnDefinitionOf)(property);
97
+ if (!inverse || (inverse.relation?.targetMultiplicity !== 'one')) {
98
+ throw new sql_join_1.RelationshipError('unsupported-relationship', column);
99
+ }
100
+ mapping = { leftColumn: 'id', rightColumn: (0, sql_join_dependencies_3.columnOf)(inverse) };
101
+ }
102
+ else {
103
+ if (inverse && (fact.cardinality === 'one-to-one') && !(0, composition_2.compositeOf)(table, column)) {
104
+ throw new sql_join_1.RelationshipError('unsupported-relationship', column);
105
+ }
106
+ mapping = { leftColumn: (0, sql_join_dependencies_3.columnOf)(property), rightColumn: 'id' };
107
+ }
108
+ }
109
+ let cardinality = fact.cardinality;
110
+ if ((cardinality === 'unknown') && inverse) {
111
+ if ((0, composition_1.componentOf)(table, column))
112
+ cardinality = (multiplicity === 'many') ? 'one-to-many' : 'one-to-one';
113
+ else if ((0, composition_2.compositeOf)(table, column)) {
114
+ cardinality = (inverse.relation?.targetMultiplicity === 'many') ? 'many-to-one' : 'one-to-one';
115
+ }
116
+ }
117
+ return {
118
+ ...mapping, cardinality, inverse: fact.inverse ?? (inverse ? `${target.name}.${String(inverse.name)}` : undefined),
119
+ multiplicity,
120
+ optional: fact.optional || !(0, required_1.requiredOf)(table, column)
121
+ };
122
+ }
123
+ function sqlRelationshipsDependsOn(overrides) {
124
+ Object.assign(dependencies, overrides);
125
+ }
126
+ //# sourceMappingURL=sql-relationships.js.map
@@ -0,0 +1,46 @@
1
+ # Framework dependency binding
2
+
3
+ The server composition root is `src/dependencies.ts:bind()`, invoked after configured export composition.
4
+ The framework supplies adapters to consumer-owned contracts through public package entries.
5
+
6
+ ## Property metadata
7
+
8
+ `propertySelectDependsOn(overrides: Partial<PropertySelectDependencies>)`, exported from
9
+ `@itrocks/framework/property-select`, merges overrides without removing unspecified defaults.
10
+ Its `authorise(request, root, path)` function returns a boolean or a promise of one. The default returns true for
11
+ every routed business class under the existing framework action access policy. The root is that class's route URL,
12
+ such as `/invoice`; no separate selector registration is needed. Each action gets its own request-bound provider;
13
+ user access is never cached globally. The adapter checks the root and all ancestor prefixes before resolving a
14
+ complete path. Optional `advice(request, root)` returns suggested relation paths; its default is empty.
15
+
16
+ Applications supply policy after composition and dependency binding, before requests start:
17
+
18
+ ```ts
19
+ import { propertySelectDependsOn } from '@itrocks/framework/property-select'
20
+
21
+ propertySelectDependsOn({
22
+ authorise: async (request, root, path) => {
23
+ const grants = request.request.session.user?.metadataPaths?.[root] ?? []
24
+ return grants.includes(path)
25
+ }
26
+ })
27
+ ```
28
+
29
+ The policy receives a transport-neutral action `Request`; application user/session semantics stay with the host.
30
+ For another request abstraction, construct `ReflectionMetadataProvider(roots, authorise)` with an asynchronous
31
+ `(root, path) => boolean` callback after reflection composition. Neither callback loads records for the selector.
32
+
33
+ `bindPropertySelect()` registers the framework actions. Reflection and path facts come from the public
34
+ [`reflect`](../../reflect/README.md) and [`reflect-path`](../../reflect-path/README.md) entries.
35
+ Presentation uses [`class-view`](../../class-view/README.md) labels and
36
+ [`property-view`](../../property-view/README.md) labels/order. Module destinations use
37
+ [`route`](../../route/README.md#api); the HTTP adapter uses `Action.jsonResponse` and `Request.data`.
38
+ Presentation/path owners are loaded when used, after export composition, so importing the binding API early does not
39
+ freeze their reflection defaults. See [authorised metadata](property-select.md) for route-backed roots, advice, DTOs
40
+ and browser use.
41
+
42
+ ## SQL adapters
43
+
44
+ [Relationship bindings](sql-relationships.md) map schema/reflection facts to `sql-join`.
45
+ [Projection bindings](sql-projection.md) supply final-owner SQL conversions to MySQL and SQL builders.
46
+ These bindings own persistence metadata; the property metadata provider does not query these adapters.
@@ -0,0 +1,125 @@
1
+ # Authorised property metadata
2
+
3
+ The server subpath `@itrocks/framework/property-select` exposes `ReflectionMetadataProvider`, `MetadataError`,
4
+ `MetadataErrorCode`, `MetadataRoot`, `PropertySelectDependencies`,
5
+ `createMetadataProvider`, `metadataConfiguration`, `propertySelectDependsOn` and `bindPropertySelect`.
6
+ Normal bootstrap binds its routes after reflection composition. `ReflectionMetadataProvider` implements the
7
+ `MetadataProvider` port from `@itrocks/property-select`.
8
+
9
+ ## Routes and access
10
+
11
+ Every business class exposed by a route is available to the selector without a `propertySelect.roots` setting.
12
+ For example, a `/invoice` route to an `Invoice` class makes `/invoice` the selector root. The framework resolves
13
+ that URL through `@itrocks/route` on each request; an unknown route or one resolving to an action is forbidden.
14
+ The browser never supplies a module destination or class name. The catalogue includes inherited fields and
15
+ accessible fields beyond the initial `List` columns.
16
+
17
+ The normal action access policy also applies to these routes. Add request-specific restrictions after framework
18
+ binding and before server startup, through `beforeFrameworkRun`:
19
+
20
+ ```ts
21
+ import { propertySelectDependsOn } from '@itrocks/framework/property-select'
22
+
23
+ propertySelectDependsOn({
24
+ authorise: async (request, root, path) => {
25
+ return request.request.session.user?.metadataPaths?.[root]?.includes(path) ?? false
26
+ }
27
+ })
28
+ ```
29
+
30
+ The callback receives the current action request, the route URL and every traversed prefix, including `''` for the
31
+ root. It must grant root and ancestor navigation as well as the destination. Its default permits every routed
32
+ business class under the existing action access policy. There is no global cache of user access decisions.
33
+ Partial dependency binding preserves unspecified defaults. Both enumeration and complete-path resolution apply
34
+ these same checks before resolving forbidden prefixes. Unknown roots and denied paths return an identical
35
+ `403 { error: 'forbidden' }` response.
36
+
37
+ An optional `advice(request, root)` dependency may return suggested relation paths. The framework validates each
38
+ suggestion against the same access policy before sending it to the browser. No advice is required for availability.
39
+
40
+ `createMetadataProvider(request, root?)` constructs a provider for that request and route URL; `root` defaults to
41
+ `request.route`. Direct construction accepts a root map and an asynchronous `(root, path) => boolean` policy, useful
42
+ for adapters with another request abstraction. Direct root maps may narrow paths without changing framework routes.
43
+ It requires the usual framework reflection composition before use; missing composition fails explicitly.
44
+ Framework `ReflectClass.propertyNames` enumerates declared types and prototype getter descriptors without
45
+ constructing domain records. Metadata uses declared property types, never getters or property values.
46
+
47
+ ## Metadata and presentation
48
+
49
+ `context(root, path, signal?)` returns one object's authorised properties, with full root-relative paths.
50
+ `resolve(root, '', signal?)` returns that root context; another path returns one property description.
51
+ Labels and order reuse `class-view` and `property-view`, with technical-name fallbacks. Order gaps after permission
52
+ filtering retain the original business order. Host translation remains separate.
53
+
54
+ Type and relation identities are opaque hashes of server-side class metadata identities; no module path is sent.
55
+ Inherited relations have the identity of their declaring metadata owner, regardless of the traversal path.
56
+ Logical inverses and N-N targets are navigable without exposing or loading link tables. Explicit relation facts
57
+ come from reflection. Component/composite declarations add an inverse only when exactly one opposite ownership
58
+ property matches; cardinality is inferred only for a known singular/plural pair. Unknown facts remain unknown.
59
+ Native `Date` properties, including nullable and optional dates, are terminal and remain selectable.
60
+ Requesting a known terminal property as a context rejects with `MetadataError('invalid-path')`. Native Date method
61
+ traversal also rejects as `invalid-path`. Both become HTTP `400 { error: 'invalid-path' }`,
62
+ without enumerating native classes.
63
+ Ambiguous traversal, missing properties, terminal traversal and unknown targets reject explicitly.
64
+
65
+ Both methods honour `AbortSignal` before work and after awaited policy decisions. They load no business records,
66
+ perform no SQL and never read `ReflectProperty.value`. Lazy search and cycle-return decisions belong to the selector.
67
+
68
+ ## Actions and browser transport
69
+
70
+ The real framework actions expose these GET endpoints:
71
+
72
+ - `/property-select/context/json?root=%2Finvoice&path=customer.address`
73
+ - `/property-select/resolve/json?root=%2Finvoice&path=customer.address.city.name`
74
+ - `/property-select/configuration/json?root=%2Finvoice`
75
+
76
+ Responses are JSON with `Cache-Control: no-store`. Invalid requests or paths return `400`; denied access returns `403`.
77
+ The configuration response contains only authorised, valid relation advice and catalogue version `1`.
78
+ Advice comes from the optional dependency; the adapter has no recommendation or persistence engine.
79
+
80
+ The public browser subpath `@itrocks/framework/property-select-metadata.js` exports `HttpMetadataProvider` and
81
+ `MetadataTransportOptions`. The normal browser composition root exposes the adapter and registers its asset.
82
+ Its import has no activation or server side effect:
83
+
84
+ ```ts
85
+ import { HttpMetadataProvider } from '@itrocks/framework/property-select-metadata.js'
86
+
87
+ const metadata = new HttpMetadataProvider()
88
+ const context = await metadata.context('/invoice', '')
89
+ const configuration = await metadata.configuration('/invoice')
90
+ ```
91
+
92
+ Options accept `endpoint` (default `/property-select`) and a substitutable `fetch` function.
93
+ Requests use same-origin credentials and forward `AbortSignal`. A cancelled response is also checked after JSON
94
+ parsing. The selector's generation checks discard obsolete responses even when the network cannot be interrupted.
95
+ Session restoration, rendered controls, searching and host column integration belong to their respective adapters.
96
+
97
+ ## Verification
98
+
99
+ `npm test` rebuilds the package and exercises existing framework tests plus metadata contracts.
100
+ `node --test --test-isolation=none` with the absolute `test/property-select-metadata.test.mjs` path gives individual
101
+ META assertions. The isolated test fixture and `test/metadata-browser.mjs` exercise the public browser module and
102
+ real request adapter, including cancellation, stale results, per-request permission changes and zero business reads.
103
+ These test resources are outside the published runtime.
104
+
105
+ ## List and pane composition
106
+
107
+ The browser composition listens for the configured container's `itrocks:right-pane-ready` event, whose detail exposes
108
+ `register(owner, content, title)`. `itrocks:right-pane-request` requests replay when consumers load after the container.
109
+ The public `bindListPane(registration)` at `@itrocks/framework/property-select-list.js` also accepts that structurally
110
+ compatible callback directly. Framework and list import no home implementation. A container without this port mounts
111
+ no list selector.
112
+
113
+ List build activation announces `itrocks:list-ready` with its public table addition adapter and configuration saver.
114
+ Only articles carrying an authorised `data-property-root` mount the selector. Dynamic navigation disposes detached
115
+ views, aborts their pending requests and removes their pane registration. Metadata requests use `HttpMetadataProvider`;
116
+ list requests keep their own scope, data source and projection/rendering responsibility.
117
+
118
+ Server binding uses the list's route URL and verifies its resolved business class, including anonymous wrappers.
119
+ The same per-request metadata policy authorises projection paths and every representative dependency, before querying.
120
+ The `/property-select/template/html` action serves only the selector's exported HTML fragment. It does not enable
121
+ arbitrary HTML asset access. The view's optional template URL allows this transport while standalone hosts retain the
122
+ adjacent static template. Neither the view nor list imports server framework code.
123
+
124
+ Selector state remains mounted-instance state at this stage; list columns retain their existing request-session
125
+ persistence. The selector session transaction and external pointer transport have separate contracts and deliveries.
@@ -0,0 +1,23 @@
1
+ # SQL projection composition
2
+
3
+ The public `@itrocks/framework/sql-projection` subpath exports `bindSqlProjection(): void` without bootstrapping a
4
+ server. Main framework `bind()` calls this same function after transformer initialisation.
5
+
6
+ ```ts
7
+ import { bindSqlProjection } from '@itrocks/framework/sql-projection'
8
+
9
+ bindSqlProjection()
10
+ ```
11
+
12
+ The binding connects MySQL read/save callbacks to the existing `SQL`/`READ` and `SQL`/`SAVE` transformer registry,
13
+ with the supplied final owner object, local property name and local raw record. It preserves lazy-property protection
14
+ handling. The adapter creates partial projection objects and handles ignored fields; the binding performs no reads.
15
+ Applications register custom property/type transformers through the public transformer package before projection.
16
+
17
+ The binding also supplies `toColumn` to sql-build and calls the public
18
+ [relationship binding](sql-relationships.md). Model stores and types remain with their existing metadata owners.
19
+ Ambiguous, unknown and invalid reflection paths are translated into relationship errors at the SQL boundary, then
20
+ into the neutral selection errors by MySQL. Directly stored scalar object fields use the builder's metadata default.
21
+
22
+ See [MySQL dependency configuration](https://github.com/itrocks-ts/mysql/blob/main/docs/dependencies.md) for the
23
+ consumer-owned callbacks and [storage](https://github.com/itrocks-ts/storage) for the partial result contract.
@@ -0,0 +1,49 @@
1
+ # SQL relationship binding
2
+
3
+ The public `@itrocks/framework/sql-relationships` subpath exports `bindSqlJoins`, `relationshipOf`,
4
+ `sqlRelationshipsDependsOn`, `SqlRelationshipDependencies`, `ColumnDefinition` and `TableDefinition`.
5
+ Importing this subpath does not bootstrap a server. Normal framework `bind()` calls `bindSqlJoins()` after composition.
6
+
7
+ `bindSqlJoins(): void` configures the public `sqlJoinDependsOn` port. Table definitions are domain types and column
8
+ definitions are framework reflected properties. Property enumeration uses type metadata without constructing records.
9
+ The adapter resolves targets through `ReflectProperty.relation` and multiplicity through `resolvePropertyPath`.
10
+ An optional or nullable property remains optional even when marked `Required`.
11
+ Optional ancestry propagates in the graph.
12
+ Unknown/ambiguous targets reject instead of being treated as scalar columns.
13
+
14
+ `relationshipOf(table, name, property): Relationship` supplies direct foreign keys using `columnOf` and `id`.
15
+ Inverse collections use the explicitly named singular back-reference or the unique matching `Composite` property.
16
+ An inverse identity may be a target property name or `TargetClass.property`, matching its exact declared class name.
17
+ Arbitrary catalogue identities need an explicit schema mapping. Several candidate composites reject as ambiguous.
18
+ A unique `Component`/`Composite` pair also supplies inverse/cardinality facts when undeclared.
19
+ Otherwise these facts remain unknown; collection multiplicity alone does not invent them.
20
+
21
+ Explicit N-N relations use the public MySQL `joinTableName` convention and renamed store names plus `_id` for link
22
+ columns, matching existing link operations. The target identity is `id`. Self-relations, colliding link column names,
23
+ and inverse 1-1 relations without an ownership direction require an explicit mapping. These cases never choose
24
+ an arbitrary back-reference or fabricate distinct columns.
25
+
26
+ `sqlRelationshipsDependsOn({ mappingOf })` merges partial adapter configuration, preserving omitted hooks.
27
+ `mappingOf(property): RelationshipMapping | undefined` defaults to `undefined`, which selects the conventions above.
28
+ A custom schema provides physical facts through this hook before constructing a graph:
29
+
30
+ ```ts
31
+ import { sqlRelationshipsDependsOn } from '@itrocks/framework/sql-relationships'
32
+
33
+ sqlRelationshipsDependsOn({
34
+ mappingOf: property => property.name === 'relatedInvoices' ? {
35
+ leftColumn: 'id',
36
+ rightColumn: 'id',
37
+ through: { table: 'invoice_relation', leftColumn: 'source_id', rightColumn: 'target_id' }
38
+ } : undefined
39
+ })
40
+ ```
41
+
42
+ Mappings describe stored schema only; the hook does not change reflection multiplicity or authorise paths.
43
+ It can also map singular inverse 1-1 relationships with `{ leftColumn: 'id', rightColumn: 'owner_id' }`.
44
+ Schema-specific code owns these overrides; no physical table metadata is added to neutral reflection decorators.
45
+ The framework imports reusable contracts through public package entries. SQL rendering remains in `sql-join`;
46
+ criterion scopes, conversion, selection policy and hydration remain with their consumers.
47
+
48
+ Run `npm test` to build server/browser outputs and synthetic model fixtures, then execute existing bootstrap/language
49
+ checks and public relationship binding tests. Test fixtures contain no application records or database connections.
package/package.json CHANGED
@@ -31,15 +31,18 @@
31
31
  "@itrocks/file": "latest",
32
32
  "@itrocks/lazy-loading": "latest",
33
33
  "@itrocks/links": "latest",
34
+ "@itrocks/list": "latest",
34
35
  "@itrocks/list-properties": "latest",
35
36
  "@itrocks/mysql": "latest",
36
37
  "@itrocks/notifications": "latest",
37
38
  "@itrocks/password": "latest",
39
+ "@itrocks/property-select": "latest",
38
40
  "@itrocks/property-translate": "latest",
39
41
  "@itrocks/property-type": "latest",
40
42
  "@itrocks/property-view": "latest",
41
43
  "@itrocks/real-viewport-height": "latest",
42
44
  "@itrocks/reflect": "latest",
45
+ "@itrocks/reflect-path": "latest",
43
46
  "@itrocks/rename": "latest",
44
47
  "@itrocks/request-response": "latest",
45
48
  "@itrocks/required": "latest",
@@ -55,8 +58,8 @@
55
58
  "@itrocks/template-insight": "latest",
56
59
  "@itrocks/transformer": "latest",
57
60
  "@itrocks/translate": "latest",
58
- "@itrocks/xtarget": "latest",
59
61
  "@itrocks/uses": "latest",
62
+ "@itrocks/xtarget": "latest",
60
63
  "air-datepicker": "^3.6",
61
64
  "date-fns": "^4.1"
62
65
  },
@@ -68,12 +71,24 @@
68
71
  "engines": {
69
72
  "node": ">=24"
70
73
  },
71
- "exports": "./cjs/framework.js",
74
+ "exports": {
75
+ ".": "./cjs/framework.js",
76
+ "./property-select": "./cjs/property-select.js",
77
+ "./property-select-actions": "./cjs/property-select-actions.js",
78
+ "./property-select-list.js": "./property-select-list.js",
79
+ "./property-select-metadata.js": "./property-select-metadata.js",
80
+ "./sql-projection": "./cjs/sql-projection.js",
81
+ "./sql-relationships": "./cjs/sql-relationships.js"
82
+ },
72
83
  "files": [
73
84
  "config.yaml",
74
85
  "favicon.png",
75
86
  "LICENSE",
76
87
  "README.md",
88
+ "docs/dependencies.md",
89
+ "docs/property-select.md",
90
+ "docs/sql-projection.md",
91
+ "docs/sql-relationships.md",
77
92
  "cjs",
78
93
  "!*.map",
79
94
  "*.csv",
@@ -103,7 +118,8 @@
103
118
  "build": "npm run build:back && npm run build:front",
104
119
  "build:back": "tsc",
105
120
  "build:front": "tsc -p src/front/tsconfig.json && node -e \"const fs=require('node:fs');for(const file of fs.readdirSync('.').filter(file=>file.endsWith('.js')||file.endsWith('.d.ts')))fs.writeFileSync(file,fs.readFileSync(file,'utf8').replaceAll('../../',''))\"",
106
- "test": "npm run build && node --test test/*.test.js"
121
+ "build:test": "tsc -p test/tsconfig.json",
122
+ "test": "npm run build && npm run build:test && node --test test/*.test.js test/*.test.mjs"
107
123
  },
108
- "version": "0.6.8"
124
+ "version": "1.0.0"
109
125
  }
@@ -0,0 +1,3 @@
1
+ import type { ListSelectorOptions } from '@itrocks/list/property-select.js';
2
+ export type PaneRegistration = (owner: object, content: HTMLElement, title: string) => ReturnType<ListSelectorOptions['mountSelector']>;
3
+ export declare function bindListPane(registration: PaneRegistration): void;
@@ -0,0 +1,61 @@
1
+ import { loadCss } from '@itrocks/asset-loader/asset-loader.js';
2
+ import { HttpMetadataProvider } from './property-select-metadata.js';
3
+ const waiting = new Map();
4
+ const mounted = new Map();
5
+ let register;
6
+ async function activate(entry) {
7
+ if (!register || !entry.article.isConnected || mounted.has(entry.article))
8
+ return;
9
+ const { ListPropertySelect } = await import('@itrocks/list/property-select.js');
10
+ if (!register || !entry.article.isConnected || mounted.has(entry.article))
11
+ return;
12
+ loadCss('/@itrocks/property-select/front/property-select.css');
13
+ loadCss('/@itrocks/table/column-add.css');
14
+ const metadata = new HttpMetadataProvider();
15
+ let integration;
16
+ try {
17
+ const configuration = await metadata.configuration(entry.article.dataset.propertyRoot);
18
+ if (!entry.article.isConnected || mounted.has(entry.article))
19
+ return;
20
+ integration = new ListPropertySelect(entry.article, {
21
+ ...entry.options, advice: configuration.advice, metadata, templateUrl: '/property-select/template/html',
22
+ mountSelector: (content, title) => register(entry.article, content, title)
23
+ });
24
+ mounted.set(entry.article, integration);
25
+ waiting.delete(entry.article);
26
+ await integration.mount();
27
+ }
28
+ catch (error) {
29
+ integration?.dispose();
30
+ mounted.delete(entry.article);
31
+ entry.article.dispatchEvent(new CustomEvent('itrocks:list-selector-error', { bubbles: true, detail: error }));
32
+ }
33
+ }
34
+ export function bindListPane(registration) {
35
+ register = registration;
36
+ for (const entry of waiting.values())
37
+ void activate(entry);
38
+ }
39
+ document.addEventListener('itrocks:right-pane-ready', event => {
40
+ bindListPane(event.detail.register);
41
+ });
42
+ document.dispatchEvent(new Event('itrocks:right-pane-request'));
43
+ document.addEventListener('itrocks:list-ready', event => {
44
+ const article = event.target.closest('article[data-property-root]');
45
+ if (!article?.dataset.propertyRoot)
46
+ return;
47
+ const entry = { article, options: event.detail };
48
+ waiting.set(article, entry);
49
+ void activate(entry);
50
+ });
51
+ new MutationObserver(() => {
52
+ for (const [article, integration] of mounted) {
53
+ if (article.isConnected)
54
+ continue;
55
+ integration.dispose();
56
+ mounted.delete(article);
57
+ }
58
+ for (const article of waiting.keys())
59
+ if (!article.isConnected)
60
+ waiting.delete(article);
61
+ }).observe(document.body, { childList: true, subtree: true });
@@ -0,0 +1,19 @@
1
+ import type { MetadataProvider } from '@itrocks/property-select/property-select.js';
2
+ import type { ObjectContext } from '@itrocks/property-select/property-select.js';
3
+ import type { PropertyDescription } from '@itrocks/property-select/property-select.js';
4
+ export type MetadataTransportOptions = {
5
+ endpoint?: string;
6
+ fetch?: typeof fetch;
7
+ };
8
+ export declare class HttpMetadataProvider implements MetadataProvider {
9
+ private readonly endpoint;
10
+ private readonly fetcher;
11
+ constructor(options?: MetadataTransportOptions);
12
+ configuration(root: string, signal?: AbortSignal): Promise<{
13
+ advice: readonly string[];
14
+ version: string;
15
+ }>;
16
+ context(root: string, path: string, signal?: AbortSignal): Promise<ObjectContext>;
17
+ private request;
18
+ resolve(root: string, path: string, signal?: AbortSignal): Promise<PropertyDescription | ObjectContext>;
19
+ }
@@ -0,0 +1,29 @@
1
+ export class HttpMetadataProvider {
2
+ endpoint;
3
+ fetcher;
4
+ constructor(options = {}) {
5
+ this.endpoint = options.endpoint ?? '/property-select';
6
+ this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
7
+ }
8
+ configuration(root, signal) {
9
+ return this.request('configuration', root, '', signal);
10
+ }
11
+ context(root, path, signal) {
12
+ return this.request('context', root, path, signal);
13
+ }
14
+ async request(operation, root, path, signal) {
15
+ signal?.throwIfAborted();
16
+ const query = new URLSearchParams({ path, root });
17
+ const response = await this.fetcher(`${this.endpoint}/${operation}/json?${query}`, {
18
+ cache: 'no-store', credentials: 'same-origin', headers: { Accept: 'application/json' }, signal
19
+ });
20
+ if (!response.ok)
21
+ throw new Error(`Metadata request failed (${response.status})`);
22
+ const value = await response.json();
23
+ signal?.throwIfAborted();
24
+ return value;
25
+ }
26
+ resolve(root, path, signal) {
27
+ return this.request('resolve', root, path, signal);
28
+ }
29
+ }