@haverstack/core 0.23.0 → 0.25.0

package/dist/stack.js

@@ -18,7 +18,7 @@ import { hashSchema, isCompatible, parseTypeId, baseIdOf, diffSchemas, isWellFor
 import { CONTENT_SEGMENT_METACHARACTERS, SEGMENT_METACHARACTER_RE, validateContent, validateContentKeys, validatePatchValues, validateReservedKeys, validateSchemaFieldNames, } from './validate.js';
 import { applyMergePatch } from './merge.js';
 import { checkAccess, groupRoleFromAssociations, isOwnerActingAlone, validatePermissions, } from './access.js';
-import { firstRecordedAttachment } from './attachment-download.js';
+import { compareRecordedAttachments } from './attachment-download.js';
 import { ChangeEmitter, RelayDelivery, Subscription, buildEmission, matchesFilter, passesUnlistedBoundary, } from './changes.js';
 import { SYSTEM_TYPES, GRANT_ACTIONS } from './types.js';
 // -------------------------------------------------------
@@ -301,12 +301,18 @@ 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.');
     }
-    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.');
+        throw new StackQueryError(`Query uses ${present && !filter?.content ? 'filter.contentPresent' : 'filter.content'}, ` +
+            'but this adapter does not declare the contentFieldQuery capability.');
     }
-    for (const key of Object.keys(filter.content)) {
+    if (present && !capabilities.contentPresenceQuery) {
+        throw new StackQueryError('Query uses filter.contentPresent, but this adapter does not declare the ' +
+            'contentPresenceQuery capability.');
+    }
+    for (const key of [...Object.keys(filter?.content ?? {}), ...(present ?? [])]) {
         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.');
@@ -358,13 +364,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.contentFieldSort) {
+            throw new StackQueryError('Query uses sort.contentField, but this adapter does not declare the contentFieldSort ' +
+                'capability.');
+        }
+        return;
+    }
+    const field = sort.field ?? 'createdAt';
+    if (!capabilities.sortableFields.includes(field)) {
+        throw new StackQueryError(`Query sorts by "${field}", which this adapter does not declare in sortableFields.`);
+    }
+}
 /** The identifier spaces a relationship target may name. */
 const TARGET_SCOPES = new Set(['record', 'entity', 'external']);
 /**
@@ -1469,6 +1510,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);
@@ -1770,37 +1812,24 @@ export class Stack {
     /**
      * mimeType is a property of the fileId, not the uploader's perspective:
      * the first metadata record for a fileId fixes it, and a conflicting
-     * later upload is rejected. Cursor-walked so earlier records past page
-     * one are seen. See docs/spec/attachments.md § The `_attachment` record
-     * type.
+     * later upload is rejected. See docs/spec/attachments.md § The
+     * `_attachment` record type.
      *
      * Best-effort by construction — check-then-create with no storage-level
      * uniqueness behind it, so two racing first uploads can both land on a
-     * concurrent server. What survives that race is the *resolution*: which
-     * record establishes the type is firstRecordedAttachment()'s total
-     * order, the same one a server serving Content-Type applies, so both
-     * sides name the same winner however many records exist.
+     * concurrent server. What survives that race is the *resolution*:
+     * getAttachmentRecords() returns the candidates in the same total order
+     * a server serving Content-Type applies, so both sides name the same
+     * winner however many records exist.
      */
     async checkAttachmentMimeTypeOnCreate(content) {
         const { fileId, mimeType } = content;
         if (typeof fileId !== 'string')
             return; // schema validation already rejected this
-        const metadataTypeId = `${SYSTEM_TYPES.ATTACHMENT}@1`;
-        const results = await queryAllPages((q) => this.query(q), {
-            filter: {
-                typeId: metadataTypeId,
-                includeDeleted: true,
-                includeUnlisted: true,
-                ...(this.features.contentFieldQuery && { content: { fileId } }),
-            },
-        });
-        const existing = this.features.contentFieldQuery
-            ? results
-            : results.filter((r) => r.content.fileId === fileId);
+        const existing = await this.getAttachmentRecords(fileId);
         if (existing.length === 0)
             return;
-        const first = firstRecordedAttachment(existing);
-        const establishedMimeType = first.content.mimeType;
+        const establishedMimeType = existing[0].content.mimeType;
         if (mimeType !== establishedMimeType) {
             // Deliberately does not name the established mimeType — that would
             // confirm a guessed fileId's content type. See the anti-oracle rule
@@ -1911,26 +1940,61 @@ export class Stack {
         return this.adapter.getAttachment(fileId);
     }
     /**
-     * Delete an attachment's bytes and its _attachment@1 metadata record(s).
-     * Throws StackConflictError if any record in the stack still references the file.
-     * Throws StackNotFoundError if neither metadata records nor bytes exist.
+     * Every `_attachment` record describing `fileId`, earliest-recorded
+     * first — so `records[0]` is the one that establishes the file's
+     * mimeType, and firstRecordedAttachment() is only needed by a caller
+     * narrowing the set further. See docs/spec/attachments.md § Finding a
+     * `fileId`'s metadata records.
+     *
+     * On `Stack` and not `StackClient`: the lookup answers a presentation
+     * question about an access decision already made, so a scoped version
+     * would impose a second, different permission check rather than a
+     * narrower correct answer.
+     */
+    async getAttachmentRecords(fileId) {
+        this.assertOpen();
+        const results = await queryAllPages((q) => this.query(q), {
+            filter: {
+                baseId: SYSTEM_TYPES.ATTACHMENT,
+                includeDeleted: true,
+                includeUnlisted: true,
+                ...(this.features.contentFieldQuery && { content: { fileId } }),
+            },
+        });
+        return results
+            .filter((r) => r.content.fileId === fileId)
+            .sort(compareRecordedAttachments);
+    }
+    /**
+     * The `_attachment` family as concrete typeIds. Resolved here rather
+     * than in the adapter, which has no baseId concept of its own — see
+     * resolveBaseIdFilter().
+     */
+    async attachmentTypeIds() {
+        const types = await this.adapter.listTypes();
+        return types.filter((t) => t.baseId === SYSTEM_TYPES.ATTACHMENT).map((t) => t.id);
+    }
+    /**
+     * Delete an attachment's bytes and every _attachment metadata record for
+     * it, family-wide. Throws StackConflictError if any record in the stack
+     * still references the file, StackNotFoundError if neither metadata
+     * records nor bytes exist.
      */
     async deleteAttachment(fileId, opts = {}) {
         this.assertOpen();
-        const metadataTypeId = `${SYSTEM_TYPES.ATTACHMENT}@1`;
         let deletedRecords;
         if (this.adapter.deleteUnreferencedAttachmentRecords) {
             // Purged inside the adapter's own transaction, so these never reach
             // delete() and are announced here instead — from the records it
             // hands back, which are the last copies that will ever exist.
-            deletedRecords = await this.adapter.deleteUnreferencedAttachmentRecords(fileId, metadataTypeId);
+            deletedRecords = await this.adapter.deleteUnreferencedAttachmentRecords(fileId, await this.attachmentTypeIds());
             const at = new Date();
             for (const record of deletedRecords) {
                 this.emitChange('hard-delete', record, { actor: Stack.purgeActor(opts), at });
             }
         }
         else {
-            deletedRecords = await this.deleteUnreferencedAttachmentRecordsFallback(fileId, metadataTypeId, opts);
+            deletedRecords = await this.deleteUnreferencedAttachmentRecordsFallback(fileId, opts);
         }
         if (!deletedRecords.length) {
             try {
@@ -1947,7 +2011,7 @@ export class Stack {
      * deleteUnreferencedAttachmentRecords(): a concurrent associate() can
      * race between the reference check below and the deletes it guards.
      */
-    async deleteUnreferencedAttachmentRecordsFallback(fileId, metadataTypeId, opts = {}) {
+    async deleteUnreferencedAttachmentRecordsFallback(fileId, opts = {}) {
         // A soft-deleted or unlisted record still counts as a reference — it
         // must find its attachments intact on undelete or relisting. See
         // docs/spec/attachments.md § Deleting attachments.
@@ -1958,20 +2022,9 @@ export class Stack {
         if (refResult.records.length > 0) {
             throw new StackConflictError('Attachment is still referenced by one or more records');
         }
-        // Cursor-walk with includeDeleted/includeUnlisted: metadata past page
-        // one, soft-deleted, or unlisted must be cleaned up too — not left
-        // pointing at deleted bytes.
-        const metaResults = await queryAllPages((q) => this.query(q), {
-            filter: {
-                typeId: metadataTypeId,
-                includeDeleted: true,
-                includeUnlisted: true,
-                ...(this.features.contentFieldQuery && { content: { fileId } }),
-            },
-        });
-        const metaRecords = this.features.contentFieldQuery
-            ? metaResults
-            : metaResults.filter((r) => r.content.fileId === fileId);
+        // Soft-deleted, unlisted, and later-version metadata is cleaned up
+        // too — none of it may be left pointing at deleted bytes.
+        const metaRecords = await this.getAttachmentRecords(fileId);
         for (const record of metaRecords) {
             await this.delete(record.id, { hard: true, ...opts });
         }
@@ -1988,9 +2041,8 @@ export class Stack {
         const graceMs = opts.graceMs ?? DEFAULT_GC_GRACE_MS;
         const dryRun = opts.dryRun ?? false;
         const now = Date.now();
-        const metadataTypeId = `${SYSTEM_TYPES.ATTACHMENT}@1`;
         const metaRecords = await queryAllPages((q) => this.query(q), {
-            filter: { typeId: metadataTypeId, includeDeleted: true, includeUnlisted: true },
+            filter: { baseId: SYSTEM_TYPES.ATTACHMENT, includeDeleted: true, includeUnlisted: true },
         });
         // Newest metadata record's createdAt per fileId, and its size (constant
         // across records sharing a fileId, since content-addressing guarantees
@@ -3172,6 +3224,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');