industrial-model 0.2.0 → 0.3.0

package/README.md

@@ -672,17 +672,29 @@ if (cursor) {
 | `NodeId`, `DataModelId` | Instance and data-model identifiers |
 | `QueryOptions`, `QuerySelect`, `WhereInput`, `SortInput` | Query input types |
 | `QueryResult`, `QueryResultItem`, `QueryResultMetadata` | Query output types |
+| `buildViewSchema`, `nodeIdSchema` | Zod schemas built from Cognite view metadata |
 | `SortDirection` | `"ascending"` \| `"descending"` |
 
-### `new IndustrialModelClient(client, dataModelId)`
+### `new IndustrialModelClient(client, dataModelId, options?)`
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `client` | `CogniteClient` | Authenticated Cognite SDK client |
 | `dataModelId` | `DataModelId` | Space, externalId, and version of the data model |
+| `options.validateResults` | `boolean` | Optional. Validate and parse query results with Zod schemas derived from Cognite view metadata |
 
 On the first query, view definitions are loaded from CDF and cached for the lifetime of the client instance.
 
+Query inputs are validated against the loaded view metadata before the Cognite request is built. Result validation is opt-in because it parses every returned item:
+
+```ts
+const model = new IndustrialModelClient(client, dataModelId, {
+  validateResults: true,
+});
+```
+
+When `validateResults` is enabled, Cognite `date` and `timestamp` view properties are converted to JavaScript `Date` objects. Without this option, result values are returned as Cognite provides them, usually ISO strings for timestamps.
+
 ### `model.query<TModel>()(options)`
 
 | Option | Type | Description |

package/dist/index.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var zod = require('zod');
+
 // src/cognite/adapter.ts
 function createCogniteAdapter(client) {
   return new CogniteSdkAdapter(client);
@@ -204,6 +206,345 @@ var FilterMapper = class {
     return value;
   }
 };
+var nodeIdSchema = zod.z.object({
+  space: zod.z.string().min(1),
+  externalId: zod.z.string().min(1)
+});
+function dateSchema(dateMode) {
+  if (dateMode === "coerce") {
+    return zod.z.preprocess(
+      (value) => typeof value === "string" || typeof value === "number" ? new Date(value) : value,
+      zod.z.date()
+    );
+  }
+  return zod.z.union([zod.z.string(), zod.z.date()]);
+}
+function propertyValueSchema(property, options = {}) {
+  const type = property.type;
+  let schema;
+  switch (type.type) {
+    case "text":
+    case "enum":
+      schema = zod.z.string();
+      break;
+    case "int32":
+    case "int64":
+      schema = zod.z.number().int();
+      break;
+    case "float32":
+    case "float64":
+      schema = zod.z.number();
+      break;
+    case "boolean":
+      schema = zod.z.boolean();
+      break;
+    case "date":
+    case "timestamp":
+      schema = dateSchema(options.dateMode);
+      break;
+    case "direct":
+      schema = nodeIdSchema;
+      break;
+    case "json":
+      schema = zod.z.unknown();
+      break;
+    default:
+      schema = zod.z.unknown();
+      break;
+  }
+  return type.list === true ? zod.z.array(schema) : schema;
+}
+function buildViewSchema(view, options = {}) {
+  const shape = {};
+  for (const [name, property] of Object.entries(view.properties)) {
+    if (isViewPropertyDefinition(property)) {
+      shape[name] = propertyValueSchema(property, options).optional();
+    }
+  }
+  return zod.z.object(shape).strict();
+}
+
+// src/mappers/query-validator.ts
+var NODE_STRING_PROPERTIES = ["externalId", "space"];
+var NODE_NUMBER_PROPERTIES = ["createdTime", "deletedTime", "lastUpdatedTime"];
+var NODE_PROPERTIES2 = /* @__PURE__ */ new Set([...NODE_STRING_PROPERTIES, ...NODE_NUMBER_PROPERTIES]);
+var SORT_DIRECTION_SCHEMA = zod.z.enum(["ascending", "descending"]);
+var recordSchema = zod.z.record(zod.z.string(), zod.z.unknown());
+var leafOps = /* @__PURE__ */ new Set([
+  "eq",
+  "in",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "exists",
+  "prefix",
+  "containsAny",
+  "containsAll"
+]);
+function isRecord(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function isLeafFilter2(value) {
+  return Object.keys(value).some((key) => leafOps.has(key));
+}
+function issuePath(path) {
+  return path.length === 0 ? "query" : path.map(String).join(".");
+}
+function formatZodIssues(error, path) {
+  return error.issues.map((issue) => `${issuePath([...path, ...issue.path])}: ${issue.message}`);
+}
+function getRelationTarget(property) {
+  if (isViewPropertyDefinition(property)) {
+    return getDirectRelationSource(property)?.externalId ?? null;
+  }
+  if (isReverseDirectRelation(property) || isEdgeConnection(property)) {
+    return property.source.externalId;
+  }
+  return null;
+}
+function baseValueSchema(property) {
+  if (property === "node-string") return zod.z.string();
+  if (property === "node-number") return zod.z.number();
+  switch (property.type.type) {
+    case "text":
+    case "enum":
+      return zod.z.string();
+    case "int32":
+    case "int64":
+      return zod.z.number().int();
+    case "float32":
+    case "float64":
+      return zod.z.number();
+    case "boolean":
+      return zod.z.boolean();
+    case "date":
+    case "timestamp":
+      return zod.z.union([zod.z.string(), zod.z.date()]);
+    case "direct":
+      return nodeIdSchema;
+    default:
+      return zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean()]);
+  }
+}
+function leafFilterSchema(property) {
+  const value = baseValueSchema(property);
+  const isList = typeof property !== "string" && property.type.list === true;
+  if (isList) {
+    return zod.z.object({
+      containsAny: zod.z.array(value).optional(),
+      containsAll: zod.z.array(value).optional(),
+      exists: zod.z.boolean().optional()
+    }).strict();
+  }
+  if (property === "node-string" || typeof property !== "string" && property.type.type === "text") {
+    return zod.z.object({
+      eq: zod.z.string().optional(),
+      in: zod.z.array(zod.z.string()).optional(),
+      prefix: zod.z.string().optional(),
+      exists: zod.z.boolean().optional()
+    }).strict();
+  }
+  if (typeof property !== "string" && property.type.type === "enum") {
+    return zod.z.object({
+      eq: zod.z.string().optional(),
+      in: zod.z.array(zod.z.string()).optional(),
+      prefix: zod.z.string().optional(),
+      exists: zod.z.boolean().optional()
+    }).strict();
+  }
+  if (property === "node-number" || typeof property !== "string" && ["int32", "int64", "float32", "float64"].includes(property.type.type ?? "")) {
+    return zod.z.object({
+      eq: value.optional(),
+      in: zod.z.array(value).optional(),
+      gt: value.optional(),
+      gte: value.optional(),
+      lt: value.optional(),
+      lte: value.optional(),
+      exists: zod.z.boolean().optional()
+    }).strict();
+  }
+  if (typeof property !== "string" && ["date", "timestamp"].includes(property.type.type ?? "")) {
+    return zod.z.object({
+      eq: value.optional(),
+      in: zod.z.array(value).optional(),
+      gt: value.optional(),
+      gte: value.optional(),
+      lt: value.optional(),
+      lte: value.optional(),
+      exists: zod.z.boolean().optional()
+    }).strict();
+  }
+  if (typeof property !== "string" && property.type.type === "boolean") {
+    return zod.z.object({
+      eq: zod.z.boolean().optional(),
+      exists: zod.z.boolean().optional()
+    }).strict();
+  }
+  if (typeof property !== "string" && property.type.type === "direct") {
+    return zod.z.object({
+      eq: nodeIdSchema.optional(),
+      in: zod.z.array(nodeIdSchema).optional(),
+      exists: zod.z.boolean().optional()
+    }).strict();
+  }
+  return zod.z.object({
+    eq: value.optional(),
+    in: zod.z.array(value).optional(),
+    exists: zod.z.boolean().optional()
+  }).strict();
+}
+var QueryValidator = class {
+  constructor(viewMapper) {
+    this.viewMapper = viewMapper;
+  }
+  async validate(options, rootView) {
+    const errors = [];
+    errors.push(...this.validateOptionsShape(options, rootView));
+    if (options.select !== void 0) {
+      errors.push(...await this.validateSelect(options.select, rootView, ["select"]));
+    }
+    if (options.filters !== void 0) {
+      errors.push(...await this.validateFilters(options.filters, rootView, ["filters"]));
+    }
+    if (options.sort !== void 0) {
+      errors.push(...this.validateSort(options.sort, rootView, ["sort"]));
+    }
+    if (errors.length > 0) {
+      throw new Error(`Invalid query options:
+${errors.map((error) => `- ${error}`).join("\n")}`);
+    }
+  }
+  validateOptionsShape(options, rootView) {
+    const schema = zod.z.object({
+      viewExternalId: zod.z.literal(rootView.externalId),
+      select: zod.z.unknown().optional(),
+      filters: zod.z.unknown().optional(),
+      sort: zod.z.unknown().optional(),
+      limit: zod.z.union([zod.z.literal(-1), zod.z.number().int().positive().max(MAX_LIMIT)]).optional(),
+      cursor: zod.z.string().nullable().optional()
+    }).strict();
+    const result = schema.safeParse(options);
+    return result.success ? [] : formatZodIssues(result.error, []);
+  }
+  async validateSelect(select, view, path) {
+    const shape = {
+      _all: zod.z.literal(true).optional()
+    };
+    for (const property of NODE_PROPERTIES2) {
+      shape[property] = zod.z.boolean().optional();
+    }
+    for (const [name, property] of Object.entries(view.properties)) {
+      const target = getRelationTarget(property);
+      if (target != null) {
+        const nestedSelect = recordSchema;
+        shape[name] = isViewPropertyDefinition(property) ? zod.z.union([zod.z.boolean(), nestedSelect]).optional() : nestedSelect.optional();
+      } else {
+        shape[name] = zod.z.boolean().optional();
+      }
+    }
+    const result = zod.z.object(shape).strict().safeParse(select);
+    if (!result.success) return formatZodIssues(result.error, path);
+    if (!isRecord(select)) return [];
+    const errors = [];
+    for (const [name, value] of Object.entries(select)) {
+      if (name === "_all" || value == null || typeof value !== "object" || Array.isArray(value)) {
+        continue;
+      }
+      const property = view.properties[name];
+      if (!property) continue;
+      const target = getRelationTarget(property);
+      if (target == null) {
+        errors.push(
+          `${issuePath([...path, name])}: property "${name}" does not support nested select`
+        );
+        continue;
+      }
+      const targetView = await this.viewMapper.getView(target);
+      errors.push(...await this.validateSelect(value, targetView, [...path, name]));
+    }
+    return errors;
+  }
+  async validateFilters(filters, view, path) {
+    const shape = {
+      AND: zod.z.union([recordSchema, zod.z.array(recordSchema)]).optional(),
+      OR: zod.z.array(recordSchema).optional(),
+      NOT: zod.z.union([recordSchema, zod.z.array(recordSchema)]).optional()
+    };
+    for (const property of NODE_STRING_PROPERTIES) {
+      shape[property] = zod.z.unknown().optional();
+    }
+    for (const property of NODE_NUMBER_PROPERTIES) {
+      shape[property] = zod.z.unknown().optional();
+    }
+    for (const property of Object.keys(view.properties)) {
+      shape[property] = zod.z.unknown().optional();
+    }
+    const result = zod.z.object(shape).strict().safeParse(filters);
+    if (!result.success) return formatZodIssues(result.error, path);
+    if (!isRecord(filters)) return [];
+    const errors = [];
+    for (const [name, value] of Object.entries(filters)) {
+      if (value == null) continue;
+      if (name === "AND" || name === "OR" || name === "NOT") {
+        const clauses = Array.isArray(value) ? value : [value];
+        for (const [index, clause] of clauses.entries()) {
+          errors.push(...await this.validateFilters(clause, view, [...path, name, index]));
+        }
+        continue;
+      }
+      if (!isRecord(value)) {
+        errors.push(`${issuePath([...path, name])}: Expected object`);
+        continue;
+      }
+      const nodePropertyType = NODE_STRING_PROPERTIES.includes(
+        name
+      ) ? "node-string" : NODE_NUMBER_PROPERTIES.includes(name) ? "node-number" : null;
+      if (nodePropertyType != null) {
+        errors.push(...this.validateLeafFilter(value, nodePropertyType, [...path, name]));
+        continue;
+      }
+      const property = view.properties[name];
+      if (!property) continue;
+      if (isViewPropertyDefinition(property)) {
+        const target2 = getDirectRelationSource(property);
+        if (target2 != null && !isLeafFilter2(value)) {
+          const targetView = await this.viewMapper.getView(target2.externalId);
+          errors.push(...await this.validateFilters(value, targetView, [...path, name]));
+        } else {
+          errors.push(...this.validateLeafFilter(value, property, [...path, name]));
+        }
+        continue;
+      }
+      const target = getRelationTarget(property);
+      if (target == null) {
+        errors.push(`${issuePath([...path, name])}: property "${name}" does not support filters`);
+        continue;
+      }
+      errors.push(
+        `${issuePath([...path, name])}: filtering through "${name}" is not supported by the query mapper`
+      );
+    }
+    return errors;
+  }
+  validateLeafFilter(value, property, path) {
+    const result = leafFilterSchema(property).safeParse(value);
+    return result.success ? [] : formatZodIssues(result.error, path);
+  }
+  validateSort(sort, view, path) {
+    const shape = {};
+    for (const property of NODE_PROPERTIES2) {
+      shape[property] = SORT_DIRECTION_SCHEMA.optional();
+    }
+    for (const [name, property] of Object.entries(view.properties)) {
+      if (isViewPropertyDefinition(property) && property.type.list !== true) {
+        shape[name] = SORT_DIRECTION_SCHEMA.optional();
+      }
+    }
+    const result = zod.z.object(shape).strict().safeParse(sort);
+    return result.success ? [] : formatZodIssues(result.error, path);
+  }
+};
 
 // src/mappers/sort-mapper.ts
 var SortMapper = class {
@@ -229,6 +570,7 @@ var QueryMapper = class {
     this.viewMapper = viewMapper;
     this.filterMapper = new FilterMapper(viewMapper);
     this.sortMapper = new SortMapper();
+    this.validator = new QueryValidator(viewMapper);
   }
   async map(options) {
     const {
@@ -241,6 +583,7 @@ var QueryMapper = class {
     } = options;
     const limit = requestedLimit === -1 ? DEFAULT_LIMIT : requestedLimit;
     const rootView = await this.viewMapper.getView(viewExternalId);
+    await this.validator.validate(options, rootView);
     const rootViewRef = toViewReference(rootView);
     const whereFilters = filters ? await this.filterMapper.map(filters, rootView) : [];
     const baseFilters = [{ hasData: [rootViewRef] }, ...whereFilters];
@@ -531,6 +874,92 @@ var QueryResultMapper = class {
     return entry;
   }
 };
+var nodeMetadataSchema = {
+  instanceType: zod.z.literal("node").optional(),
+  space: zod.z.string(),
+  externalId: zod.z.string(),
+  version: zod.z.number().optional(),
+  createdTime: zod.z.number().optional(),
+  deletedTime: zod.z.number().optional(),
+  lastUpdatedTime: zod.z.number().optional(),
+  _edges: zod.z.record(zod.z.string(), zod.z.unknown()).optional()
+};
+function isListRelation(property) {
+  if (isViewPropertyDefinition(property)) {
+    return isListDirectRelation(property);
+  }
+  if (isReverseDirectRelation(property)) {
+    return property.connectionType === "multi_reverse_direct_relation" || property.targetsList === true;
+  }
+  return isEdgeConnection(property);
+}
+function isRecord2(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+var QueryResultValidator = class {
+  constructor(viewMapper) {
+    this.viewMapper = viewMapper;
+  }
+  async parseItems(rootViewExternalId, items, select) {
+    const rootView = await this.viewMapper.getView(rootViewExternalId);
+    const schema = await this.buildResultSchema(rootView, MAX_DEPENDENCY_DEPTH, select);
+    const result = zod.z.array(schema).safeParse(items);
+    if (!result.success) {
+      throw new Error(
+        `Invalid query result:
+${result.error.issues.map((issue) => `- ${issue.path.map(String).join(".")}: ${issue.message}`).join("\n")}`
+      );
+    }
+    return result.data;
+  }
+  async buildResultSchema(view, remainingDepth, select) {
+    const shape = { ...nodeMetadataSchema };
+    const includeAllProperties = select == null || select._all === true;
+    for (const [name, property] of Object.entries(view.properties)) {
+      const isSelected = includeAllProperties || name in select;
+      if (!isSelected) continue;
+      const nestedSelect = isRecord2(select?.[name]) ? select[name] : void 0;
+      if (isViewPropertyDefinition(property)) {
+        const relationSource = getDirectRelationSource(property);
+        if (relationSource) {
+          shape[name] = await this.buildRelationSchema(
+            property,
+            relationSource.externalId,
+            remainingDepth,
+            nestedSelect
+          );
+        } else {
+          shape[name] = propertyValueSchema(property, { dateMode: "coerce" }).optional();
+        }
+        continue;
+      }
+      if (isReverseDirectRelation(property) || isEdgeConnection(property)) {
+        shape[name] = await this.buildRelationSchema(
+          property,
+          property.source.externalId,
+          remainingDepth,
+          nestedSelect
+        );
+      }
+    }
+    const schema = zod.z.object(shape);
+    return includeAllProperties ? schema.strict() : schema;
+  }
+  async buildRelationSchema(property, targetViewExternalId, remainingDepth, select) {
+    const isList = isListRelation(property);
+    const fallbackSchema = isViewPropertyDefinition(property) ? propertyValueSchema(property, { dateMode: "coerce" }) : zod.z.unknown();
+    if (remainingDepth <= 0 || select == null) {
+      return fallbackSchema.optional();
+    }
+    const targetView = await this.viewMapper.getView(targetViewExternalId);
+    const nestedSchema = await this.buildResultSchema(targetView, remainingDepth - 1, select);
+    if (isViewPropertyDefinition(property)) {
+      const nestedRelationSchema = isList ? zod.z.array(nestedSchema) : nestedSchema;
+      return zod.z.union([nestedRelationSchema, fallbackSchema]).optional();
+    }
+    return (isList ? zod.z.array(nestedSchema) : nestedSchema).optional();
+  }
+};
 
 // src/mappers/view-mapper.ts
 var ViewMapper = class {
@@ -681,15 +1110,18 @@ function buildDependenciesQuery(previousQuery, nodesParent, nodesChildren, leafC
 
 // src/client.ts
 var IndustrialModelClient = class {
-  constructor(client, dataModelId) {
+  constructor(client, dataModelId, options = {}) {
     const cognite = createCogniteAdapter(client);
     this.cognite = cognite;
     const viewMapper = new ViewMapper(cognite, dataModelId);
     this.queryMapper = new QueryMapper(viewMapper);
     this.resultMapper = new QueryResultMapper(viewMapper);
+    this.resultValidator = new QueryResultValidator(viewMapper);
+    this.validateResults = options.validateResults ?? false;
   }
   query() {
-    return (options) => this.queryInternal(options);
+    const execute = (options) => this.queryInternal(options);
+    return execute;
   }
   async queryInternal(options) {
     const { viewExternalId, limit = DEFAULT_LIMIT } = options;
@@ -707,7 +1139,8 @@ var IndustrialModelClient = class {
         mapNodesAndEdges(queryResult),
         dependenciesData
       );
-      const pageResult = await this.resultMapper.mapNodes(viewExternalId, queryResultData);
+      const mappedPageResult = await this.resultMapper.mapNodes(viewExternalId, queryResultData);
+      const pageResult = this.validateResults ? await this.resultValidator.parseItems(viewExternalId, mappedPageResult, options.select) : mappedPageResult;
       const nextCursor = queryResult.nextCursor[viewExternalId] ?? null;
       const isLastPage = pageResult.length < limit || !nextCursor;
       const resolvedCursor = isLastPage ? null : nextCursor;
@@ -739,5 +1172,7 @@ var IndustrialModelClient = class {
 };
 
 exports.IndustrialModelClient = IndustrialModelClient;
+exports.buildViewSchema = buildViewSchema;
+exports.nodeIdSchema = nodeIdSchema;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map