@cratis/scene.model 4.2.1 → 4.4.0

package/queries/QueryBinding.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryArgumentBinding } from './QueryArgumentBinding';
+import { QueryResultBinding } from './QueryResultBinding';
+
+/**
+ * The value of a `QueryReference` property: which query, what feeds each of its parameters, and which result
+ * fields feed what. Every connection is stated explicitly - nothing is matched by name or position.
+ */
+export interface QueryBinding {
+    /** The stable identity of the bound {@link QueryCandidate}. */
+    queryId: string;
+
+    /** The query name the binding registry resolves at runtime - a snapshot of the candidate's name when bound. */
+    query: string;
+
+    arguments: QueryArgumentBinding[];
+    results: QueryResultBinding[];
+}
+
+export const QueryBindingPropertyNames: (keyof QueryBinding)[] = ['queryId', 'query', 'arguments', 'results'];

package/queries/QueryCandidate.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryOrigin } from './QueryOrigin';
+import { QueryParameter } from './QueryParameter';
+import { QueryResultField } from './QueryResultField';
+import { QueryResultShape } from './QueryResultShape';
+
+/**
+ * A query a property may be bound to, as supplied by the host.
+ *
+ * Scene never discovers queries itself - it has no idea what the application's backend offers. The host (Studio)
+ * works out which queries are in scope for the thing being edited and hands them in, in this shape, which is
+ * what keeps discovery out of the model and binding validation inside it.
+ */
+export interface QueryCandidate {
+    /** The query's stable identity, which survives a rename. Bindings refer to it. */
+    id: string;
+
+    /** The query's display name - the name the binding registry resolves at runtime. */
+    name: string;
+
+    /** The path from the editing scope down to the query's owner, outermost first. */
+    origin: QueryOrigin[];
+
+    parameters: QueryParameter[];
+
+    /** How many results the query produces. Accepts the {@link QueryResultShape} members or their string values. */
+    resultShape: `${QueryResultShape}`;
+
+    /** The fields of one result item. */
+    resultFields: QueryResultField[];
+}
+
+export const QueryCandidatePropertyNames: (keyof QueryCandidate)[] = [
+    'id', 'name', 'origin', 'parameters', 'resultShape', 'resultFields',
+];

package/queries/QueryOrigin.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { QueryOriginKind } from './QueryOriginKind';
+
+/**
+ * One step on the path from the editing scope down to the owner of a query.
+ *
+ * `kind` accepts both the {@link QueryOriginKind} members and their plain string values (`'feature'`,
+ * `'slice'`), so a host that builds candidates from JSON does not have to import the enum.
+ */
+export interface QueryOrigin {
+    kind: `${QueryOriginKind}`;
+    id: string;
+    name: string;
+}
+
+export const QueryOriginPropertyNames: (keyof QueryOrigin)[] = ['kind', 'id', 'name'];

package/queries/QueryOriginKind.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * What kind of model element owns a query.
+ */
+export enum QueryOriginKind {
+    /** A feature of the application model. */
+    Feature = 'feature',
+
+    /** A slice within a feature. */
+    Slice = 'slice',
+}

package/queries/QueryParameter.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * One parameter a query takes.
+ */
+export interface QueryParameter {
+    name: string;
+
+    /** The parameter's type name, compared with the type of whatever is bound to it. */
+    type: string;
+
+    required: boolean;
+}
+
+export const QueryParameterPropertyNames: (keyof QueryParameter)[] = ['name', 'type', 'required'];

package/queries/QueryResultBinding.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Connects one field of a query's result to something the consuming component displays.
+ */
+export interface QueryResultBinding {
+    /** What the field feeds: a column key, a label slot - whatever the component's descriptor names. */
+    target: string;
+
+    /** The name of the result field. */
+    field: string;
+}
+
+export const QueryResultBindingPropertyNames: (keyof QueryResultBinding)[] = ['target', 'field'];

package/queries/QueryResultField.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * One field of what a query returns.
+ */
+export interface QueryResultField {
+    name: string;
+
+    /** The field's type name. */
+    type: string;
+
+    /** Whether the field identifies the item - the key a component can use for item identity. */
+    isIdentity?: boolean;
+}
+
+export const QueryResultFieldPropertyNames: (keyof QueryResultField)[] = ['name', 'type', 'isIdentity'];

package/queries/QueryResultShape.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * How many results a query produces. Decides which component can bind to it: a table wants a collection, a
+ * single-result display wants a single or an optional single.
+ */
+export enum QueryResultShape {
+    /** Zero or more items. */
+    Collection = 'collection',
+
+    /** Exactly one item. */
+    Single = 'single',
+
+    /** One item, or none. */
+    OptionalSingle = 'optional-single',
+}

package/queries/index.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './QueryResultShape';
+export * from './QueryOriginKind';
+export * from './QueryOrigin';
+export * from './QueryParameter';
+export * from './QueryResultField';
+export * from './QueryCandidate';
+export * from './QueryArgumentBinding';
+export * from './QueryResultBinding';
+export * from './QueryBinding';