@haverstack/core 0.24.0 → 0.26.0

package/dist/stack.js

@@ -298,21 +298,38 @@ export class StackQueryError extends StackError {
  * § Capability-gated filters.
  */
 export function assertQueryCapabilities(filter, capabilities) {
-    if (filter?.search && !capabilities.fullTextSearch) {
-        throw new StackQueryError('Query uses filter.search, but this adapter does not declare the fullTextSearch capability.');
+    const { content: reach, contentPresent, search } = capabilities.filter;
+    if (filter?.search && !search) {
+        throw new StackQueryError('Query uses filter.search, but this adapter does not declare the filter.search capability.');
     }
-    if (!filter?.content)
+    const present = filter?.contentPresent?.length ? filter.contentPresent : undefined;
+    if (!filter?.content && !present)
         return;
-    if (!capabilities.contentFieldQuery) {
-        throw new StackQueryError('Query uses filter.content, but this adapter does not declare the contentFieldQuery capability.');
+    if (reach === 'none') {
+        throw new StackQueryError(`Query uses ${present && !filter?.content ? 'filter.contentPresent' : 'filter.content'}, ` +
+            'but this adapter declares filter.content: "none".');
     }
-    for (const key of Object.keys(filter.content)) {
-        if (parseContentFilterKey(key).length > 1 && !capabilities.nestedContentQuery) {
-            throw new StackQueryError(`Query uses the nested content path "${key}", but this adapter does not declare ` +
-                'the nestedContentQuery capability.');
+    if (present && !contentPresent) {
+        throw new StackQueryError('Query uses filter.contentPresent, but this adapter does not declare the ' +
+            'filter.contentPresent capability.');
+    }
+    for (const key of [...Object.keys(filter?.content ?? {}), ...(present ?? [])]) {
+        if (parseContentFilterKey(key).length > 1 && reach !== 'path') {
+            throw new StackQueryError(`Query uses the nested content path "${key}", but this adapter declares ` +
+                `filter.content: "${reach}".`);
         }
     }
 }
+/**
+ * Whether a single-segment content filter can be pushed down to the
+ * adapter. Callers that read a content field pair this with an in-memory
+ * predicate over the wider result, so the query stays correct against an
+ * adapter that reaches no content at all — the rung comparison lives here
+ * rather than at each of them.
+ */
+function filtersContent(features) {
+    return features.filter.content !== 'none';
+}
 /** The longest path both SQLite engines can execute — see the spec link below. */
 const MAX_CONTENT_PATH_SEGMENTS = 32;
 /**
@@ -358,13 +375,48 @@ const VALID_SORT_DIRECTIONS = new Set(['asc', 'desc']);
 export function assertValidSort(sort) {
     if (!sort)
         return;
+    if (sort.field !== undefined && sort.contentField !== undefined) {
+        throw new StackQueryError('A sort names either a native field or a content field, never both.');
+    }
     if (sort.field !== undefined && !VALID_SORT_FIELDS.has(sort.field)) {
         throw new StackQueryError(`Invalid sort field "${sort.field}": expected one of createdAt, updatedAt, version.`);
     }
+    if (sort.contentField !== undefined) {
+        // Parsed by the same rule a filter key is, so a name a filter could
+        // never address is not one a sort can either — then held to one
+        // segment, because a value inside an array or object has no single
+        // position to order its record by (docs/spec/data-model.md
+        // § Sorting by a content field).
+        if (parseContentFilterKey(sort.contentField).length > 1) {
+            throw new StackQueryError(`Invalid sort content field "${sort.contentField}": sorting reaches top-level fields only.`);
+        }
+    }
     if (sort.direction !== undefined && !VALID_SORT_DIRECTIONS.has(sort.direction)) {
         throw new StackQueryError(`Invalid sort direction "${sort.direction}": expected "asc" or "desc".`);
     }
 }
+/**
+ * Fail loud rather than silently reorder: an adapter that can't honor the
+ * requested sort would otherwise answer in some other order, which a
+ * caller paging a bounded window has no way to notice. The companion to
+ * assertQueryCapabilities(), split from it because a sort is not a filter
+ * — see docs/spec/data-model.md § Capability-gated filters.
+ */
+export function assertSortCapability(sort, capabilities) {
+    if (!sort)
+        return;
+    if (sort.contentField !== undefined) {
+        if (!capabilities.sort.contentField) {
+            throw new StackQueryError('Query uses sort.contentField, but this adapter does not declare the sort.contentField ' +
+                'capability.');
+        }
+        return;
+    }
+    const field = sort.field ?? 'createdAt';
+    if (!capabilities.sort.fields.includes(field)) {
+        throw new StackQueryError(`Query sorts by "${field}", which this adapter does not declare in sort.fields.`);
+    }
+}
 /** The identifier spaces a relationship target may name. */
 const TARGET_SCOPES = new Set(['record', 'entity', 'external']);
 /**
@@ -439,8 +491,8 @@ export function assertValidRelatedTo(relatedTo) {
 }
 /**
  * Thrown when an attachment upload exceeds the adapter's declared
- * `maxAttachmentBytes` ceiling — checked client-side before any bytes are
- * sent; a server still enforces 413 authoritatively regardless. See
+ * `limits.attachmentBytes` ceiling — checked client-side before any bytes
+ * are sent; a server still enforces 413 authoritatively regardless. See
  * docs/spec/wire-format.md § Attachments.
  */
 export class StackPayloadTooLargeError extends StackError {
@@ -473,25 +525,25 @@ export class StackTimeoutError extends StackError {
     }
 }
 /** Shared by Stack.putAttachment() and ScopedStack.putAttachment(). */
-function assertAttachmentSize(byteLength, maxAttachmentBytes) {
-    if (maxAttachmentBytes !== null && byteLength > maxAttachmentBytes) {
-        throw new StackPayloadTooLargeError(`Attachment (${byteLength} bytes) exceeds the ${maxAttachmentBytes}-byte limit.`);
+function assertAttachmentSize(byteLength, attachmentBytes) {
+    if (attachmentBytes !== null && byteLength > attachmentBytes) {
+        throw new StackPayloadTooLargeError(`Attachment (${byteLength} bytes) exceeds the ${attachmentBytes}-byte limit.`);
     }
 }
 /**
  * The content half of the same pre-check, on Stack.create() and
- * Stack.update(). Local adapters declare `maxContentBytes: null` and skip
+ * Stack.update(). Local adapters declare `limits.contentBytes: null` and skip
  * the serialization entirely; only a server declares a ceiling, and its
  * own request-size limit stays authoritative — this just spares an app the
  * round trip and gives it a typed failure instead of a 413 it has to
  * interpret. See docs/spec/wire-format.md § Request size limits.
  */
-function assertContentSize(content, maxContentBytes, what) {
-    if (maxContentBytes === null)
+function assertContentSize(content, contentBytes, what) {
+    if (contentBytes === null)
         return;
     const byteLength = new TextEncoder().encode(JSON.stringify(content)).length;
-    if (byteLength > maxContentBytes) {
-        throw new StackPayloadTooLargeError(`${what} (${byteLength} bytes) exceeds the ${maxContentBytes}-byte limit.`);
+    if (byteLength > contentBytes) {
+        throw new StackPayloadTooLargeError(`${what} (${byteLength} bytes) exceeds the ${contentBytes}-byte limit.`);
     }
 }
 /**
@@ -742,13 +794,13 @@ async function findFirstMatch(run, query, predicate, max = QUERY_ALL_MAX) {
  * hardcoded, so a caller not permitted to set it can omit it instead of
  * having query() throw.
  */
-async function lookupEntityByDid(run, did, contentFieldQuery, includeUnlisted) {
+async function lookupEntityByDid(run, did, canFilterContent, includeUnlisted) {
     const record = await findFirstMatch(run, {
         filter: {
             baseId: SYSTEM_TYPES.ENTITY,
             includeDeleted: true,
             ...(includeUnlisted && { includeUnlisted: true }),
-            ...(contentFieldQuery && { content: { did } }),
+            ...(canFilterContent && { content: { did } }),
         },
     }, (r) => r.content.did === did);
     return record ?? null;
@@ -829,7 +881,7 @@ export class Stack {
     }
     /**
      * Idempotent bootstrap for StackOptions.ownerProfile. Filters by family
-     * only (contentFieldQuery is capability-gated) and matches `content.did`
+     * only (content filtering is capability-gated) and matches `content.did`
      * in memory, cursor-walking so an owner card past page one isn't missed
      * and duplicated. The probe must be blind to nothing the binding rules
      * see, or it mints a card they then refuse and the stack won't open with
@@ -852,7 +904,7 @@ export class Stack {
         return this.adapter.ownerEntityId;
     }
     async getEntityByDid(did) {
-        return lookupEntityByDid((q) => this.query(q), did, this.features.contentFieldQuery, true);
+        return lookupEntityByDid((q) => this.query(q), did, filtersContent(this.features), true);
     }
     async getOwnerEntity() {
         return this.getEntityByDid(this.ownerEntityId);
@@ -1129,7 +1181,7 @@ export class Stack {
         if (errors.length > 0) {
             throw new StackValidationError(errors);
         }
-        assertContentSize(content, this.features.maxContentBytes, 'Content');
+        assertContentSize(content, this.features.limits.contentBytes, 'Content');
         if (typeId === `${SYSTEM_TYPES.ATTACHMENT}@1`) {
             await this.checkAttachmentMimeTypeOnCreate(content);
         }
@@ -1255,7 +1307,7 @@ export class Stack {
         }
         // The patch is what travels, so the patch is what's measured — a small
         // patch against a large record is not an oversized request.
-        assertContentSize(content, this.features.maxContentBytes, 'Patch');
+        assertContentSize(content, this.features.limits.contentBytes, 'Patch');
         // Merge (RFC 7396 / JSON Merge Patch): null values delete a field.
         const merged = applyMergePatch(existing.content, content);
         const errors = validateContent(merged, type.schema);
@@ -1469,6 +1521,7 @@ export class Stack {
         const { presentAt, filter, limit: rawLimit, ...rest } = query;
         assertQueryCapabilities(filter, this.adapter.capabilities);
         assertValidSort(query.sort);
+        assertSortCapability(query.sort, this.adapter.capabilities);
         assertValidRelatedTo(filter?.relatedTo);
         const limit = rawLimit !== undefined ? Math.min(rawLimit, MAX_QUERY_LIMIT) : undefined;
         const resolvedFilter = await this.resolveBaseIdFilter(filter);
@@ -1619,7 +1672,7 @@ export class Stack {
         if (errors.length > 0) {
             throw new StackValidationError(errors);
         }
-        assertContentSize(content, this.features.maxContentBytes, 'Content');
+        assertContentSize(content, this.features.limits.contentBytes, 'Content');
         const fromFamily = baseIdOf(existing.typeId);
         const toFamily = baseIdOf(toTypeId);
         const existingContent = existing.content;
@@ -1736,7 +1789,7 @@ export class Stack {
                 baseId: family,
                 includeDeleted: true,
                 includeUnlisted: true,
-                ...(this.features.contentFieldQuery && { content: { [field]: value } }),
+                ...(filtersContent(this.features) && { content: { [field]: value } }),
             },
         }, (r) => r.id !== excludeId && r.content[field] === value);
         if (clash) {
@@ -1877,7 +1930,7 @@ export class Stack {
      */
     async putAttachment(data, mimeType, filename, appId) {
         this.assertOpen();
-        assertAttachmentSize(data.byteLength, this.features.maxAttachmentBytes);
+        assertAttachmentSize(data.byteLength, this.features.limits.attachmentBytes);
         if (this.adapter.putAttachmentWithMetadata) {
             // The metadata record is written inside the adapter, so create()
             // never sees it and this is the only place it can be announced.
@@ -1916,7 +1969,7 @@ export class Stack {
                 baseId: SYSTEM_TYPES.ATTACHMENT,
                 includeDeleted: true,
                 includeUnlisted: true,
-                ...(this.features.contentFieldQuery && { content: { fileId } }),
+                ...(filtersContent(this.features) && { content: { fileId } }),
             },
         });
         return results
@@ -2980,7 +3033,7 @@ export class ScopedStack {
         }
         if (this.subjectEntityId === this.stack.ownerEntityId)
             return true;
-        return this.stack.features.contentFieldQuery
+        return filtersContent(this.stack.features)
             ? (await this.stack.query({
                 filter: {
                     typeId: `${SYSTEM_TYPES.ATTACHMENT}@1`,
@@ -3169,7 +3222,7 @@ export class ScopedStack {
      * docs/spec/identity.md § DID bindings.
      */
     async getEntityByDid(did) {
-        return lookupEntityByDid((q) => this.query(q), did, this.stack.features.contentFieldQuery, this.ownerActingAlone);
+        return lookupEntityByDid((q) => this.query(q), did, filtersContent(this.stack.features), this.ownerActingAlone);
     }
     async getOwnerEntity() {
         return this.getEntityByDid(this.stack.ownerEntityId);
@@ -3182,6 +3235,7 @@ export class ScopedStack {
      */
     async query(query = {}) {
         assertValidSort(query.sort);
+        assertSortCapability(query.sort, this.stack.features);
         assertValidRelatedTo(query.filter?.relatedTo);
         if (query.filter?.includeUnlisted && !this.ownerActingAlone) {
             throw new StackPermissionError('includeUnlisted is owner-only');
@@ -3284,7 +3338,7 @@ export class ScopedStack {
                 baseId: SYSTEM_TYPES.APP,
                 includeDeleted: true,
                 includeUnlisted: true,
-                ...(this.stack.features.contentFieldQuery && {
+                ...(filtersContent(this.stack.features) && {
                     content: { did: this.principalEntityId },
                 }),
             },
@@ -3511,7 +3565,7 @@ export class ScopedStack {
             throw new StackPermissionError(`No create grant for type "${SYSTEM_TYPES.ATTACHMENT}@1"`);
         }
         await this.requireAppIdMatchesPrincipal(appId);
-        assertAttachmentSize(data.byteLength, this.features.maxAttachmentBytes);
+        assertAttachmentSize(data.byteLength, this.features.limits.attachmentBytes);
         const fileId = await this.adapter.putAttachment(data);
         return this.stack.create(`${SYSTEM_TYPES.ATTACHMENT}@1`, {
             fileId,