@distrohelena/canton-typescript-sdk 1.0.5 → 1.0.7

package/README.md

@@ -839,6 +839,26 @@ uses `[{ createdAt: "desc" }, { contractId: "asc" }]`. `exercises` intentionally
 because the v1 PQS profile does not declare a stable key. The manager validates
 the selected PQS schema profile before its first PQS query.
 
+Payload and JSON-path filters accept `as: "timestamp"` to compare ISO timestamps
+at microsecond precision in both PQS and memory:
+
+```typescript
+where: {
+    payload: {
+        match: {
+            expiresAt: { as: "timestamp", gt: "2026-09-09T12:00:00.000001Z" },
+        },
+    },
+}
+```
+
+For relational JSON fields, use `{ path: ["expiresAt"], as: "timestamp", gt: value }`.
+Values require a timezone and at most six fractional digits. Equivalent instants
+compare equally regardless of timezone offset or fractional padding. Omit `as`
+or use `as: "text"` for string comparisons; `like` and `ilike` require text.
+This filter option does not change timestamp projections or lifecycle fields
+represented as JavaScript `Date`, which retain millisecond precision.
+
 - Ledger endpoint:
 - `versionService.getLedgerApiVersionAsync(...)`: `json`, `grpc`
 - `healthService.checkAsync(...)`: `grpc` only

package/dist/cjs/daml-interface/runtime/daml-value-converter.js

@@ -120,20 +120,24 @@ function decodeProtobufRecord(record, descriptor, registry, path) {
         for (const field of descriptor.fields) {
             const sourceField = fields.find((candidate) => candidate.label === field.damlLabel);
             if (sourceField === undefined) {
-                throw materializationError(fieldPath(path, field.propertyName), "required record field is absent");
+                output[field.propertyName] = decodeMissingRecordField(field, fieldPath(path, field.propertyName));
+                continue;
             }
             output[field.propertyName] = decodeRequiredProtobufValue(sourceField.value, field.type, registry, fieldPath(path, field.propertyName));
         }
-        if (fields.length !== descriptor.fields.length) {
+        if (fields.some((field) => !descriptor.fields.some((descriptorField) => descriptorField.damlLabel === field.label))) {
             throw materializationError(path, "record contains an unexpected field");
         }
     }
     else {
-        if (fields.length !== descriptor.fields.length) {
+        if (fields.length > descriptor.fields.length) {
             throw materializationError(path, "record has the wrong number of positional fields");
         }
         descriptor.fields.forEach((field, index) => {
-            output[field.propertyName] = decodeRequiredProtobufValue(fields[index]?.value, field.type, registry, fieldPath(path, field.propertyName));
+            const sourceField = fields[index];
+            output[field.propertyName] = sourceField === undefined
+                ? decodeMissingRecordField(field, fieldPath(path, field.propertyName))
+                : decodeRequiredProtobufValue(sourceField.value, field.type, registry, fieldPath(path, field.propertyName));
         });
     }
     return new daml_values_js_1.DamlRecord(output);
@@ -212,11 +216,13 @@ function decodeJsonTextMap(value, descriptor, registry, path) {
 function decodeJsonRecord(value, descriptor, registry, path) {
     const output = Object.create(null);
     if (Array.isArray(value)) {
-        if (value.length !== descriptor.fields.length) {
+        if (value.length > descriptor.fields.length) {
             throw materializationError(path, "record has the wrong number of positional fields");
         }
         descriptor.fields.forEach((field, index) => {
-            output[field.propertyName] = decodeDamlValue({ kind: "json", value: value[index] }, field.type, registry, fieldPath(path, field.propertyName));
+            output[field.propertyName] = index >= value.length
+                ? decodeMissingRecordField(field, fieldPath(path, field.propertyName))
+                : decodeDamlValue({ kind: "json", value: value[index] }, field.type, registry, fieldPath(path, field.propertyName));
         });
         return new daml_values_js_1.DamlRecord(output);
     }
@@ -229,12 +235,19 @@ function decodeJsonRecord(value, descriptor, registry, path) {
     }
     for (const field of descriptor.fields) {
         if (!Object.hasOwn(record, field.damlLabel)) {
-            throw materializationError(fieldPath(path, field.propertyName), "required record field is absent");
+            output[field.propertyName] = decodeMissingRecordField(field, fieldPath(path, field.propertyName));
+            continue;
         }
         output[field.propertyName] = decodeDamlValue({ kind: "json", value: Reflect.get(record, field.damlLabel) }, field.type, registry, fieldPath(path, field.propertyName));
     }
     return new daml_values_js_1.DamlRecord(output);
 }
+function decodeMissingRecordField(field, path) {
+    if (field.type.kind === "optional") {
+        return undefined;
+    }
+    throw materializationError(path, "required record field is absent");
+}
 function decodeJsonVariant(value, descriptor, registry, path) {
     const envelope = requireObject(value, path, "variant");
     const tag = requireString(Reflect.get(envelope, "tag"), path, "variant tag");

package/dist/cjs/query/canonical/in-memory-query-evaluator.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.InMemoryQueryEvaluator = void 0;
 const query_dataset_js_1 = require("./query-dataset.js");
 const query_schema_js_1 = require("./query-schema.js");
+const query_timestamp_js_1 = require("./query-timestamp.js");
 /** Reference evaluator for normalized canonical plans; it intentionally has no transport concerns. */
 class InMemoryQueryEvaluator {
     execute(dataset, query) {
@@ -40,8 +41,10 @@ class InMemoryQueryEvaluator {
                 return predicate.quantifier === "one" ? result[0] === true : predicate.quantifier === "some" ? result.some(Boolean) : predicate.quantifier === "none" ? !result.some(Boolean) : result.every(Boolean);
             }
             case "scalar": {
-                const actual = at(row, predicate.path);
-                const expected = predicate.value;
+                const raw = at(row, predicate.path);
+                const convert = (value) => predicate.as === "timestamp" && value !== null && value !== undefined ? (0, query_timestamp_js_1.timestampMicroseconds)(value) : value;
+                const actual = predicate.operator === "is" || predicate.operator === "isNot" ? raw : convert(raw);
+                const expected = Array.isArray(predicate.value) ? predicate.value.map(convert) : convert(predicate.value);
                 switch (predicate.operator) {
                     case "equals": return actual !== null && actual !== undefined && expected !== null && expected !== undefined && equal(actual, expected);
                     case "in": return actual !== null && actual !== undefined && Array.isArray(expected) && expected.some((candidate) => candidate !== null && candidate !== undefined && equal(actual, candidate));
@@ -171,7 +174,10 @@ function freeze(value) {
     return Object.freeze(value);
 }
 function equal(left, right) {
-    if (left instanceof Date) {
+    if (typeof left === "bigint" || typeof right === "bigint") {
+        return left === right;
+    }
+    else if (left instanceof Date) {
         return left.toISOString() === (right instanceof Date ? right.toISOString() : String(right));
     }
     else if (right instanceof Date) {
@@ -196,7 +202,7 @@ function compare(left, right) {
     return leftValue < rightValue ? -1 : leftValue > rightValue ? 1 : 0;
 }
 function numeric(value) {
-    return typeof value === "string" && /^-?\d+$/.test(value) ? BigInt(value) : typeof value === "number" && Number.isFinite(value) ? BigInt(value) : undefined;
+    return typeof value === "bigint" ? value : typeof value === "string" && /^-?\d+$/.test(value) ? BigInt(value) : typeof value === "number" && Number.isFinite(value) ? BigInt(value) : undefined;
 }
 function postgresCompare(left, right, direction) {
     const leftNull = left === null || left === undefined;

package/dist/cjs/query/canonical/query-normalizer.js

@@ -7,6 +7,7 @@ exports.normalizeCount = normalizeCount;
 exports.normalizeAggregate = normalizeAggregate;
 exports.normalizeGroupBy = normalizeGroupBy;
 const model_types_js_1 = require("../model-types.js");
+const query_timestamp_js_1 = require("./query-timestamp.js");
 const query_schema_js_1 = require("./query-schema.js");
 const scalarOperators = new Set([
     "equals", "in", "is", "isNot", "lt", "lte", "gt", "gte", "like", "ilike", "has",
@@ -236,7 +237,8 @@ function normalizeScalarFilter(relation, field, value) {
 function normalizeJsonFilter(field, value) {
     const filter = object(value, `${field} JSON filter`);
     const path = jsonPath(filter.path, `${field}.path`);
-    const entries = Object.entries(filter).filter(([operator]) => operator !== "path");
+    const as = normalizeTimestampFilterType(filter);
+    const entries = Object.entries(filter).filter(([operator]) => operator !== "path" && operator !== "as");
     if (entries.length === 0) {
         throw new Error(`${field} JSON filter must contain an operator`);
     }
@@ -245,11 +247,14 @@ function normalizeJsonFilter(field, value) {
             throw new Error(`${operator} is not supported for ${field}`);
         }
         validateOperatorValue(operator, operand, field, "string", true);
-        return { kind: "scalar", path: [field, ...path], operator: operator, value: operand };
+        if (as !== undefined)
+            validateTimestampOperand(operator, operand);
+        return { kind: "scalar", path: [field, ...path], operator: operator, value: operand, ...(as === undefined ? {} : { as }) };
     });
 }
 function normalizePayloadScalarFilter(path, value) {
-    const entries = Object.entries(value);
+    const as = normalizeTimestampFilterType(value);
+    const entries = Object.entries(value).filter(([operator]) => operator !== "as");
     if (entries.length === 0) {
         throw new Error("payload filter must not be empty");
     }
@@ -258,9 +263,26 @@ function normalizePayloadScalarFilter(path, value) {
             throw new Error(`${operator} is not supported for payload`);
         }
         validateOperatorValue(operator, operand, "payload", "string", false);
-        return { kind: "scalar", path, operator: operator, value: operand };
+        if (as !== undefined)
+            validateTimestampOperand(operator, operand);
+        return { kind: "scalar", path, operator: operator, value: operand, ...(as === undefined ? {} : { as }) };
     });
 }
+function normalizeTimestampFilterType(filter) {
+    if (filter.as !== undefined && filter.as !== "text" && filter.as !== "timestamp") {
+        throw new Error("JSON filter as must be text or timestamp");
+    }
+    return filter.as === "timestamp" ? "timestamp" : undefined;
+}
+function validateTimestampOperand(operator, value) {
+    if (operator === "like" || operator === "ilike") {
+        throw new Error(`${operator} is not supported for timestamp filters`);
+    }
+    for (const entry of Array.isArray(value) ? value : [value]) {
+        if (entry !== null)
+            (0, query_timestamp_js_1.timestampMicroseconds)(entry);
+    }
+}
 function normalizeTemplateScalarFilter(field, value) {
     if (!isFilter(value)) {
         throw new Error(`templateId.${field} must be a filter object`);

package/dist/cjs/query/canonical/query-timestamp.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timestampMicroseconds = timestampMicroseconds;
+/** Parse an explicit ISO timestamp without passing its fractional seconds through Date. */
+function timestampMicroseconds(value) {
+    const match = typeof value === "string"
+        ? /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2})(?:\.(\d{1,6}))?(Z|[+-]\d{2}:\d{2})$/.exec(value)
+        : null;
+    if (match === null) {
+        throw new Error("Invalid timestamp: expected ISO date-time with a timezone and at most six fractional digits");
+    }
+    const base = `${match[1]}T${match[2]}`;
+    const milliseconds = Date.parse(`${base}Z`);
+    if (!Number.isFinite(milliseconds) || new Date(milliseconds).toISOString().slice(0, 19) !== base) {
+        throw new Error("Invalid timestamp calendar date or time");
+    }
+    const zone = match[4];
+    const hours = zone === "Z" ? 0 : Number(zone.slice(1, 3));
+    const minutes = zone === "Z" ? 0 : Number(zone.slice(4, 6));
+    if (hours > 15 || minutes > 59) {
+        throw new Error("Invalid timestamp timezone offset");
+    }
+    const offset = BigInt((hours * 60 + minutes) * (zone[0] === "-" ? -1 : 1));
+    const micros = BigInt(milliseconds) * 1000n + BigInt((match[3] ?? "").padEnd(6, "0")) - offset * 60000000n;
+    if (micros < -62135596800000000n || micros > 253402300799999999n) {
+        throw new Error("Timestamp is outside the DAML ledger range");
+    }
+    return micros;
+}

package/dist/cjs/query/pqs/pqs-sql-compiler.js

@@ -257,7 +257,9 @@ function compileCanonicalPredicate(relation, predicate, alias, profile, add, log
             ? `${compileCanonicalPhysicalField(relation, field, alias, profile)} #>> ${add(path)}::text[]`
             : compileCanonicalPhysicalField(relation, field, alias, profile);
     const inverseEventType = relation === "__events" && field === "type" && (predicate.operator === "equals" || predicate.operator === "in");
-    const expression = inverseEventType ? qualified(alias, column) : canonicalExpression;
+    const expression = predicate.as === "timestamp" && predicate.operator !== "is" && predicate.operator !== "isNot"
+        ? `(${canonicalExpression})::timestamptz`
+        : inverseEventType ? qualified(alias, column) : canonicalExpression;
     const value = inverseEventType ? physicalEventType(predicate.value) : predicate.value;
     const sql = { equals: "=", lt: "<", lte: "<=", gt: ">", gte: ">=", like: "like", ilike: "ilike" }[predicate.operator];
     if (predicate.operator === "is")
@@ -265,7 +267,7 @@ function compileCanonicalPredicate(relation, predicate, alias, profile, add, log
     if (predicate.operator === "isNot")
         return `${expression} is not null`;
     if (predicate.operator === "in")
-        return value.length === 0 ? "false" : `${expression} = any(${add(value)})`;
+        return value.length === 0 ? "false" : `${expression} = any(${add(value)}${predicate.as === "timestamp" ? "::timestamptz[]" : ""})`;
     if (predicate.operator === "has")
         return `${add(value)} = any(${qualified(alias, column)})`;
     if (sql === undefined)

package/dist/daml-interface/runtime/daml-value-converter.js

@@ -116,20 +116,24 @@ function decodeProtobufRecord(record, descriptor, registry, path) {
         for (const field of descriptor.fields) {
             const sourceField = fields.find((candidate) => candidate.label === field.damlLabel);
             if (sourceField === undefined) {
-                throw materializationError(fieldPath(path, field.propertyName), "required record field is absent");
+                output[field.propertyName] = decodeMissingRecordField(field, fieldPath(path, field.propertyName));
+                continue;
             }
             output[field.propertyName] = decodeRequiredProtobufValue(sourceField.value, field.type, registry, fieldPath(path, field.propertyName));
         }
-        if (fields.length !== descriptor.fields.length) {
+        if (fields.some((field) => !descriptor.fields.some((descriptorField) => descriptorField.damlLabel === field.label))) {
             throw materializationError(path, "record contains an unexpected field");
         }
     }
     else {
-        if (fields.length !== descriptor.fields.length) {
+        if (fields.length > descriptor.fields.length) {
             throw materializationError(path, "record has the wrong number of positional fields");
         }
         descriptor.fields.forEach((field, index) => {
-            output[field.propertyName] = decodeRequiredProtobufValue(fields[index]?.value, field.type, registry, fieldPath(path, field.propertyName));
+            const sourceField = fields[index];
+            output[field.propertyName] = sourceField === undefined
+                ? decodeMissingRecordField(field, fieldPath(path, field.propertyName))
+                : decodeRequiredProtobufValue(sourceField.value, field.type, registry, fieldPath(path, field.propertyName));
         });
     }
     return new DamlRecord(output);
@@ -208,11 +212,13 @@ function decodeJsonTextMap(value, descriptor, registry, path) {
 function decodeJsonRecord(value, descriptor, registry, path) {
     const output = Object.create(null);
     if (Array.isArray(value)) {
-        if (value.length !== descriptor.fields.length) {
+        if (value.length > descriptor.fields.length) {
             throw materializationError(path, "record has the wrong number of positional fields");
         }
         descriptor.fields.forEach((field, index) => {
-            output[field.propertyName] = decodeDamlValue({ kind: "json", value: value[index] }, field.type, registry, fieldPath(path, field.propertyName));
+            output[field.propertyName] = index >= value.length
+                ? decodeMissingRecordField(field, fieldPath(path, field.propertyName))
+                : decodeDamlValue({ kind: "json", value: value[index] }, field.type, registry, fieldPath(path, field.propertyName));
         });
         return new DamlRecord(output);
     }
@@ -225,12 +231,19 @@ function decodeJsonRecord(value, descriptor, registry, path) {
     }
     for (const field of descriptor.fields) {
         if (!Object.hasOwn(record, field.damlLabel)) {
-            throw materializationError(fieldPath(path, field.propertyName), "required record field is absent");
+            output[field.propertyName] = decodeMissingRecordField(field, fieldPath(path, field.propertyName));
+            continue;
         }
         output[field.propertyName] = decodeDamlValue({ kind: "json", value: Reflect.get(record, field.damlLabel) }, field.type, registry, fieldPath(path, field.propertyName));
     }
     return new DamlRecord(output);
 }
+function decodeMissingRecordField(field, path) {
+    if (field.type.kind === "optional") {
+        return undefined;
+    }
+    throw materializationError(path, "required record field is absent");
+}
 function decodeJsonVariant(value, descriptor, registry, path) {
     const envelope = requireObject(value, path, "variant");
     const tag = requireString(Reflect.get(envelope, "tag"), path, "variant tag");

package/dist/query/canonical/in-memory-query-evaluator.js

@@ -1,5 +1,6 @@
 import { createQueryDataset, immutableQueryValue, relatedQueryRows } from "./query-dataset.js";
 import { queryRelationEdges, queryRelationMetadata } from "./query-schema.js";
+import { timestampMicroseconds } from "./query-timestamp.js";
 /** Reference evaluator for normalized canonical plans; it intentionally has no transport concerns. */
 export class InMemoryQueryEvaluator {
     execute(dataset, query) {
@@ -37,8 +38,10 @@ export class InMemoryQueryEvaluator {
                 return predicate.quantifier === "one" ? result[0] === true : predicate.quantifier === "some" ? result.some(Boolean) : predicate.quantifier === "none" ? !result.some(Boolean) : result.every(Boolean);
             }
             case "scalar": {
-                const actual = at(row, predicate.path);
-                const expected = predicate.value;
+                const raw = at(row, predicate.path);
+                const convert = (value) => predicate.as === "timestamp" && value !== null && value !== undefined ? timestampMicroseconds(value) : value;
+                const actual = predicate.operator === "is" || predicate.operator === "isNot" ? raw : convert(raw);
+                const expected = Array.isArray(predicate.value) ? predicate.value.map(convert) : convert(predicate.value);
                 switch (predicate.operator) {
                     case "equals": return actual !== null && actual !== undefined && expected !== null && expected !== undefined && equal(actual, expected);
                     case "in": return actual !== null && actual !== undefined && Array.isArray(expected) && expected.some((candidate) => candidate !== null && candidate !== undefined && equal(actual, candidate));
@@ -167,7 +170,10 @@ function freeze(value) {
     return Object.freeze(value);
 }
 function equal(left, right) {
-    if (left instanceof Date) {
+    if (typeof left === "bigint" || typeof right === "bigint") {
+        return left === right;
+    }
+    else if (left instanceof Date) {
         return left.toISOString() === (right instanceof Date ? right.toISOString() : String(right));
     }
     else if (right instanceof Date) {
@@ -192,7 +198,7 @@ function compare(left, right) {
     return leftValue < rightValue ? -1 : leftValue > rightValue ? 1 : 0;
 }
 function numeric(value) {
-    return typeof value === "string" && /^-?\d+$/.test(value) ? BigInt(value) : typeof value === "number" && Number.isFinite(value) ? BigInt(value) : undefined;
+    return typeof value === "bigint" ? value : typeof value === "string" && /^-?\d+$/.test(value) ? BigInt(value) : typeof value === "number" && Number.isFinite(value) ? BigInt(value) : undefined;
 }
 function postgresCompare(left, right, direction) {
     const leftNull = left === null || left === undefined;

package/dist/query/canonical/query-ast.d.ts

@@ -12,6 +12,7 @@ export type QueryPredicate = {
     readonly path: readonly string[];
     readonly operator: ScalarOperator;
     readonly value: unknown;
+    readonly as?: "timestamp";
 } | {
     readonly kind: "relation";
     readonly edge: string;

package/dist/query/canonical/query-normalizer.js

@@ -1,4 +1,5 @@
 import { assertQueryOrderBy, assertQueryPageArgs } from "../model-types.js";
+import { timestampMicroseconds } from "./query-timestamp.js";
 import { queryRelationEdges, queryRelationMetadata, } from "./query-schema.js";
 const scalarOperators = new Set([
     "equals", "in", "is", "isNot", "lt", "lte", "gt", "gte", "like", "ilike", "has",
@@ -227,7 +228,8 @@ function normalizeScalarFilter(relation, field, value) {
 function normalizeJsonFilter(field, value) {
     const filter = object(value, `${field} JSON filter`);
     const path = jsonPath(filter.path, `${field}.path`);
-    const entries = Object.entries(filter).filter(([operator]) => operator !== "path");
+    const as = normalizeTimestampFilterType(filter);
+    const entries = Object.entries(filter).filter(([operator]) => operator !== "path" && operator !== "as");
     if (entries.length === 0) {
         throw new Error(`${field} JSON filter must contain an operator`);
     }
@@ -236,11 +238,14 @@ function normalizeJsonFilter(field, value) {
             throw new Error(`${operator} is not supported for ${field}`);
         }
         validateOperatorValue(operator, operand, field, "string", true);
-        return { kind: "scalar", path: [field, ...path], operator: operator, value: operand };
+        if (as !== undefined)
+            validateTimestampOperand(operator, operand);
+        return { kind: "scalar", path: [field, ...path], operator: operator, value: operand, ...(as === undefined ? {} : { as }) };
     });
 }
 function normalizePayloadScalarFilter(path, value) {
-    const entries = Object.entries(value);
+    const as = normalizeTimestampFilterType(value);
+    const entries = Object.entries(value).filter(([operator]) => operator !== "as");
     if (entries.length === 0) {
         throw new Error("payload filter must not be empty");
     }
@@ -249,9 +254,26 @@ function normalizePayloadScalarFilter(path, value) {
             throw new Error(`${operator} is not supported for payload`);
         }
         validateOperatorValue(operator, operand, "payload", "string", false);
-        return { kind: "scalar", path, operator: operator, value: operand };
+        if (as !== undefined)
+            validateTimestampOperand(operator, operand);
+        return { kind: "scalar", path, operator: operator, value: operand, ...(as === undefined ? {} : { as }) };
     });
 }
+function normalizeTimestampFilterType(filter) {
+    if (filter.as !== undefined && filter.as !== "text" && filter.as !== "timestamp") {
+        throw new Error("JSON filter as must be text or timestamp");
+    }
+    return filter.as === "timestamp" ? "timestamp" : undefined;
+}
+function validateTimestampOperand(operator, value) {
+    if (operator === "like" || operator === "ilike") {
+        throw new Error(`${operator} is not supported for timestamp filters`);
+    }
+    for (const entry of Array.isArray(value) ? value : [value]) {
+        if (entry !== null)
+            timestampMicroseconds(entry);
+    }
+}
 function normalizeTemplateScalarFilter(field, value) {
     if (!isFilter(value)) {
         throw new Error(`templateId.${field} must be a filter object`);

package/dist/query/canonical/query-timestamp.d.ts

@@ -0,0 +1,2 @@
+/** Parse an explicit ISO timestamp without passing its fractional seconds through Date. */
+export declare function timestampMicroseconds(value: unknown): bigint;

package/dist/query/canonical/query-timestamp.js

@@ -0,0 +1,26 @@
+/** Parse an explicit ISO timestamp without passing its fractional seconds through Date. */
+export function timestampMicroseconds(value) {
+    const match = typeof value === "string"
+        ? /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2})(?:\.(\d{1,6}))?(Z|[+-]\d{2}:\d{2})$/.exec(value)
+        : null;
+    if (match === null) {
+        throw new Error("Invalid timestamp: expected ISO date-time with a timezone and at most six fractional digits");
+    }
+    const base = `${match[1]}T${match[2]}`;
+    const milliseconds = Date.parse(`${base}Z`);
+    if (!Number.isFinite(milliseconds) || new Date(milliseconds).toISOString().slice(0, 19) !== base) {
+        throw new Error("Invalid timestamp calendar date or time");
+    }
+    const zone = match[4];
+    const hours = zone === "Z" ? 0 : Number(zone.slice(1, 3));
+    const minutes = zone === "Z" ? 0 : Number(zone.slice(4, 6));
+    if (hours > 15 || minutes > 59) {
+        throw new Error("Invalid timestamp timezone offset");
+    }
+    const offset = BigInt((hours * 60 + minutes) * (zone[0] === "-" ? -1 : 1));
+    const micros = BigInt(milliseconds) * 1000n + BigInt((match[3] ?? "").padEnd(6, "0")) - offset * 60000000n;
+    if (micros < -62135596800000000n || micros > 253402300799999999n) {
+        throw new Error("Timestamp is outside the DAML ledger range");
+    }
+    return micros;
+}

package/dist/query/model-types.d.ts

@@ -20,6 +20,8 @@ export interface ArrayMembershipFilter {
 }
 export interface JsonPathFilter {
     readonly path: readonly [string, ...readonly string[]];
+    /** Compare ISO timestamps at microsecond precision; omitted means text. */
+    readonly as?: "text" | "timestamp";
     readonly equals?: string;
     readonly in?: readonly string[];
     readonly lt?: string;
@@ -138,6 +140,8 @@ export interface TemplateId {
     readonly entityName: string;
 }
 type PayloadValueFilter = {
+    readonly as?: "text" | "timestamp";
+} & ({
     readonly equals: string;
     readonly lt?: never;
     readonly lte?: never;
@@ -193,7 +197,7 @@ type PayloadValueFilter = {
     readonly gt?: never;
     readonly gte?: never;
     readonly like?: never;
-};
+});
 export type PayloadMatch = {
     readonly [field: string]: PayloadMatch | PayloadValueFilter;
 };

package/dist/query/pqs/pqs-sql-compiler.js

@@ -248,7 +248,9 @@ function compileCanonicalPredicate(relation, predicate, alias, profile, add, log
             ? `${compileCanonicalPhysicalField(relation, field, alias, profile)} #>> ${add(path)}::text[]`
             : compileCanonicalPhysicalField(relation, field, alias, profile);
     const inverseEventType = relation === "__events" && field === "type" && (predicate.operator === "equals" || predicate.operator === "in");
-    const expression = inverseEventType ? qualified(alias, column) : canonicalExpression;
+    const expression = predicate.as === "timestamp" && predicate.operator !== "is" && predicate.operator !== "isNot"
+        ? `(${canonicalExpression})::timestamptz`
+        : inverseEventType ? qualified(alias, column) : canonicalExpression;
     const value = inverseEventType ? physicalEventType(predicate.value) : predicate.value;
     const sql = { equals: "=", lt: "<", lte: "<=", gt: ">", gte: ">=", like: "like", ilike: "ilike" }[predicate.operator];
     if (predicate.operator === "is")
@@ -256,7 +258,7 @@ function compileCanonicalPredicate(relation, predicate, alias, profile, add, log
     if (predicate.operator === "isNot")
         return `${expression} is not null`;
     if (predicate.operator === "in")
-        return value.length === 0 ? "false" : `${expression} = any(${add(value)})`;
+        return value.length === 0 ? "false" : `${expression} = any(${add(value)}${predicate.as === "timestamp" ? "::timestamptz[]" : ""})`;
     if (predicate.operator === "has")
         return `${add(value)} = any(${qualified(alias, column)})`;
     if (sql === undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@distrohelena/canton-typescript-sdk",
-    "version": "1.0.5",
+    "version": "1.0.7",
     "license": "Apache-2.0",
     "type": "module",
     "main": "./dist/index.js",