@simtlix/simfinity-core 3.16.0 → 3.18.0

package/README.md

@@ -84,3 +84,7 @@ pinned to the facade's exact version, including under pnpm or Yarn PnP. A late
 call fails without deleting installed metadata. Migrate clients selecting
 `__Field.extensions` before opting out. See the [descriptor reference](https://simtlix.github.io/simfinity.js/reference/client-descriptor.html)
 for the format, protected HTTP access and composition limits.
+
+`queryFeatures.valuePath: true` opts an adapter into stored-field comparisons and requires `referenceEmptiness: true`; only true enables it. `valuePath` is nullable on all three generated filter inputs and is mutually exclusive with a supplied `value` (including null). Core validates both operand paths, their logical types, visibility and collection correlation, and preserves outer origins internally. `createQueryPlan` adds `operand?: QueryOperand` with `{ up, path, joins? }` and a null value placeholder; same-frame scope unions live in predicate `joins`, ancestor scopes in operand `joins`. Literal nodes stay unchanged. `describeModels` retains additive `enumName` and effective `temporalName` metadata. See [the comparison rules and limits](https://simtlix.github.io/simfinity.js/guide/queries.html#compare-stored-fields) and [compiler contract](https://simtlix.github.io/simfinity.js/guide/sql-plugins.html#query-features).
+
+Version 3.18.0 adds `queryFeatures.elementFrames: true` for embedded object `ANY`/`ALL`/`NONE` and structural `$parent` operands. It requires `quantifiers`, `referenceEmptiness` and `valuePath`, all true. Missing/null lists and null items contribute no elements; `ALL` and `NONE` are true without elements. Parent traversal includes single embedded containers and stops at entity boundaries. Filters preserve selected arrays and outer row cardinality. See [the syntax and examples](https://simtlix.github.io/simfinity.js/guide/queries.html#embedded-object-lists-and-parent); versions through 3.17.0 do not support this extension.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-core",
-  "version": "3.16.0",
+  "version": "3.18.0",
   "description": "Driver-free GraphQL runtime and model metadata for Simfinity",
   "type": "module",
   "main": "./src/index.js",

package/src/metadata.js

@@ -54,7 +54,7 @@ const scalarDescription = (type) => {
       if (storedValues.has(stored) && !Object.is(storedValues.get(stored), entry.value)) invalid(`Enum storage collision in ${type.name}: distinct internal values serialize to ${stored}`);
       storedValues.set(stored, entry.value);
     }
-    return { scalar: 'Enum', values: [...storedValues.keys()], enumValues: type.getValues().map(({ name, value }) => ({ name, value })) };
+    return { scalar: 'Enum', enumName: type.name, values: [...storedValues.keys()], enumValues: type.getValues().map(({ name, value }) => ({ name, value })) };
   }
   // The walk stops on a type that still has a base only where the chain repeats.
   if (rootScalar(type).baseScalarType) invalid(`Cyclic base scalar ${type.name}`);
@@ -63,7 +63,7 @@ const scalarDescription = (type) => {
   if (!['String', 'ID', 'Int', 'Float', 'Boolean', 'DateTime'].includes(scalar)) {
     invalid(`Unsupported scalar ${type.name}: declare a supported baseScalarType`);
   }
-  return { scalar };
+  return { scalar, ...(scalar === 'DateTime' ? { temporalName: name } : {}) };
 };
 
 // The version field of a protected entity, described the same way whether the type carries Simfinity's

package/src/query-comparisons.js

@@ -0,0 +1,54 @@
+import SimfinityError from './errors/simfinity.error.js';
+
+const fail = (message, code = 'INVALID_FILTER_VALUE') => { throw new SimfinityError(message, code, 400); };
+const equality = new Set(['EQ', 'NE']);
+const ordered = new Set(['LT', 'LTE', 'GT', 'GTE']);
+const text = new Set(['LIKE', 'STARTS_WITH', 'ENDS_WITH']);
+const temporal = new Set(['DateTime', 'Date', 'Time']);
+
+/** A nullable optional path selects a field operand only when non-null and non-undefined. */
+export const hasValuePath = (carrier) => carrier?.valuePath !== undefined && carrier?.valuePath !== null;
+
+/** Validate the public operand syntax before resolving either path. Literal carriers are unchanged. */
+export const validateComparisonOperand = (carrier) => {
+  if (!hasValuePath(carrier)) return null;
+  if (carrier.value !== undefined) fail('A filter cannot supply both value and valuePath');
+  if (typeof carrier.valuePath !== 'string') fail('valuePath requires a string field path');
+  if (!/^(?:\$parent\.)*[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(carrier.valuePath)) {
+    fail('valuePath requires a field path optionally preceded by embedded $parent prefixes', 'INVALID_FILTER_PATH');
+  }
+  return carrier.valuePath;
+};
+
+const typeOf = (field, path) => {
+  if (field.identity || field.scalar === 'ID') return 'ID';
+  if (field.scalar === 'Enum') {
+    if (!field.enumName) fail(`Field comparison on ${path} requires logical enumName metadata`, 'UNSUPPORTED_QUERY');
+    return `Enum:${field.enumName}`;
+  }
+  if (temporal.has(field.scalar)) {
+    if (!field.temporalName) fail(`Field comparison on ${path} requires effective temporalName metadata`, 'UNSUPPORTED_QUERY');
+    return field.temporalName;
+  }
+  return field.scalar;
+};
+
+/** Logical comparison rules shared by runtime/model validation and hand-built engine plans. */
+export const validateComparisonTypes = (left, right, operator = 'EQ', leftPath = 'left', rightPath = 'right') => {
+  if (right.list) fail(`The right operand ${rightPath} must be a scalar, not a list`, 'INVALID_FILTER_PATH');
+  if (!equality.has(operator) && !ordered.has(operator) && !text.has(operator)) {
+    fail(`${operator} does not accept valuePath`, 'INVALID_FILTER_OPERATOR');
+  }
+  if (left.list && !equality.has(operator)) fail(`${operator} does not accept a list left operand`, 'INVALID_FILTER_OPERATOR');
+  const a = typeOf(left, leftPath);
+  const b = typeOf(right, rightPath);
+  const numeric = ['Int', 'Float'].includes(a) && ['Int', 'Float'].includes(b);
+  const supported = numeric || (a === b && (['String', 'Boolean', 'ID'].includes(a) || temporal.has(a) || a?.startsWith('Enum:')));
+  if (!supported || left.version || right.version) {
+    fail(`Incompatible field comparison: ${leftPath} (${a}) and ${rightPath} (${b})`);
+  }
+  if (text.has(operator) && a !== 'String') fail(`${operator} requires String operands`, 'INVALID_FILTER_OPERATOR');
+  if (ordered.has(operator) && !numeric && a !== 'String' && !temporal.has(a)) {
+    fail(`${operator} does not order ${a} operands`, 'INVALID_FILTER_OPERATOR');
+  }
+};

package/src/query-context.js

@@ -0,0 +1,117 @@
+import { getNamedType, isEnumType, isObjectType } from 'graphql';
+import SimfinityError from './errors/simfinity.error.js';
+import { effectiveScalarName } from './metadata.js';
+import { isVirtualField } from './relation-storage.js';
+import { graphqlStep, modelStep } from './query-emptiness.js';
+
+const fail = (message, code = 'INVALID_FILTER_PATH') => { throw new SimfinityError(message, code, 400); };
+const relation = (step) => ['reference', 'collection'].includes(step.kind);
+const partsOf = (path) => (Array.isArray(path) ? path : typeof path === 'string' ? path.split('.') : []);
+const bindingOf = (ctx) => ctx.binding ?? { depth: 0, path: [] };
+
+const childContext = (ctx, step) => ({
+  ...ctx,
+  ...(ctx.gqltype ? { gqltype: step.node } : { entity: step.target ?? ctx.entity, fields: step.node }),
+  parent: ['embedded', 'embeddedList'].includes(step.kind) ? ctx : undefined,
+  absolute: [...(ctx.absolute ?? []), step.name],
+  binding: { depth: bindingOf(ctx).depth, path: [...bindingOf(ctx).path, step.name] },
+});
+
+// One schema-path resolver for these operations, using the same step classifications as emptiness.
+// Model contexts retain embedded fields locally; relation steps switch to the target entity.
+export const resolveQueryContext = (path, ctx, { onStep, virtualLabel, ordinaryCondition = false } = {}) => {
+  const parts = partsOf(path);
+  const invalid = parts.findIndex((part) => typeof part !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(part));
+  if (!parts.length || invalid !== -1) {
+    if (ordinaryCondition && invalid > 0) fail(`Invalid filter path segment: "${parts[invalid]}"`, 'INVALID_FILTER_PATH');
+    fail('Invalid filter path', 'INVALID_FILTER_PATH');
+  }
+  let current = ctx;
+  const steps = [];
+  const raw = [];
+  for (const [index, name] of parts.entries()) {
+    let step;
+    if (ctx.gqltype) {
+      const fields = isObjectType(current.gqltype) ? current.gqltype.getFields() : null;
+      const field = fields && Object.hasOwn(fields, name) ? fields[name] : null;
+      if (!field) fail(ordinaryCondition && index === 0 ? `Unknown filter field: ${name}`
+        : `Unknown field ${parts.slice(0, index + 1).join('.')}`, 'INVALID_FILTER_FIELD');
+      if (isVirtualField(field)) {
+        const label = virtualLabel?.(field) ?? parts.join('.');
+        fail(`Query path ${label} uses the virtual field ${current.gqltype.name}.${name}, which is not stored`, 'INVALID_FILTER_FIELD');
+      }
+      step = graphqlStep(name, field);
+      const type = getNamedType(field.type);
+      step.scalar = isEnumType(type) ? 'Enum' : effectiveScalarName(type);
+      step.enumName = isEnumType(type) ? type.name : undefined;
+      step.temporalName = ['Date', 'Time', 'DateTime'].includes(step.scalar) ? step.scalar : undefined;
+      step.version = step.scalar === 'RecordVersion' || step.scalar === 'Version';
+      raw.push(field);
+    } else {
+      const fields = current.fields ?? current.models?.entities.find((entity) => entity.name === current.entity)?.fields;
+      const field = fields?.find((item) => item.name === name && !item.private);
+      if (!field) fail(`Unknown field ${parts.slice(0, index + 1).join('.')}`, 'INVALID_FILTER_FIELD');
+      step = { ...field, ...modelStep(field) };
+      if (relation(step)) step.node = ctx.models?.entities.find((entity) => entity.name === step.target)?.fields;
+      raw.push(field);
+    }
+    onStep?.(step, current);
+    steps.push(step);
+    if (index < parts.length - 1 && !step.node) fail(`Field ${name} cannot be traversed`, 'INVALID_FILTER_PATH');
+    current = childContext(current, step);
+  }
+  return { steps, raw, end: current };
+};
+
+/** Bind the endpoint while retaining its actual structural containers. */
+export const enterQueryFrame = (context, path) => {
+  const { end } = resolveQueryContext(path, context);
+  return { ...end, frameParent: context, binding: { depth: bindingOf(context).depth + 1, path: [] } };
+};
+
+/** Resolve public comparison paths from their filter carrier, before normalization. */
+export const resolveComparisonContext = (valuePath, context, prefix = '') => {
+  const parts = partsOf(valuePath);
+  if (parts[0] !== '$parent') {
+    return { resolved: resolveQueryContext([...(prefix ? partsOf(prefix) : []), ...parts], context), context };
+  }
+  let current = prefix ? resolveQueryContext(prefix, context).end : context;
+  while (parts[0] === '$parent') {
+    if (!current.parent) fail('$parent requires an embedded containing object');
+    current = current.parent;
+    parts.shift();
+  }
+  const resolved = resolveQueryContext(parts, current);
+  const binding = bindingOf(current);
+  return { resolved, context: current, path: parts,
+    container: { up: bindingOf(context).depth - binding.depth, path: binding.path } };
+};
+
+/** A structural operand may address only one of this context's bound containers. */
+export const resolveContainerContext = (container, context) => {
+  if (!container || typeof container !== 'object' || Array.isArray(container)
+    || Object.keys(container).some((key) => !['up', 'path'].includes(key))
+    || !Number.isSafeInteger(container.up) || container.up < 0 || !Array.isArray(container.path)
+    || container.path.some((part) => typeof part !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(part))) {
+    fail('Invalid embedded comparison container');
+  }
+  for (let parent = context.parent; parent; parent = parent.parent) {
+    const binding = bindingOf(parent);
+    if (bindingOf(context).depth - binding.depth === container.up
+      && binding.path.length === container.path.length && binding.path.every((part, index) => part === container.path[index])) return parent;
+  }
+  fail('Comparison container is not an embedded ancestor');
+};
+
+/** Recover a collector entry's bound context without inferring parents from dotted strings. */
+export const queryEntryContext = (entry, context) => {
+  let current = context;
+  for (const frame of entry.frames) {
+    const anchor = frame.construct.__implicit === true && Array.isArray(frame.construct.__anchor) ? frame.construct.__anchor : [];
+    current = enterQueryFrame(current, [...anchor, ...partsOf(frame.path)]);
+  }
+  return current;
+};
+
+/** Distinct marker namespace for a public parent operand before its binding is normalized. */
+export const parentScopePrefix = (valuePath) => typeof valuePath === 'string' ? valuePath.match(/^(?:\$parent\.)+/)?.[0] ?? '' : '';