@haverstack/core 0.41.0 → 0.43.0

package/dist/query-validation.d.ts

@@ -1,11 +1,10 @@
 /**
- * Query and association validation
+ * Query validation
  * -------------------------------------------------------
- * The sanitizers a query passes through before any adapter sees it, plus
- * the relationship-target rules an association is held to. Both sides of
- * the same job: a discriminated union and a `QuerySort` field are compile-
- * time promises, and a server mapping a request body onto either supplies
- * raw JSON that no compiler has seen.
+ * The sanitizers a query passes through before any adapter sees it. A
+ * `QuerySort` field or a filter's discriminated union is a compile-time
+ * promise, and a server mapping a request onto either supplies raw JSON
+ * that no compiler has seen.
  *
  * These live in the invariant layer for the reason validation and
  * `_config` protection do — so no adapter can forget one. `assertQueryCapabilities`
@@ -16,16 +15,24 @@
  * the query — one rule, one answer.
  * See docs/spec/data-model.md § Capability-gated filters.
  */
-import type { ValidationError } from './validate.js';
-import type { Association, AssociationEdit, AuthorityAssociation, DataAssociation, GrantGrantee, JournalQuery, VersionsQuery, QuerySort, RecordFilter, RelationshipTarget, StackCapabilities } from './types.js';
+import type { AdapterQuery, PlainQuery, StackQuery, JournalQuery, QuerySort, RecordFilter, StackCapabilities, VersionsQuery } from './types/index.js';
 /**
- * Fail loud rather than silently widen: a filter the adapter can't honor
- * would otherwise be dropped, returning an unfiltered superset presented
- * as the filtered result. Shared by Stack.query() and
- * APIAdapter.queryRecords(). See docs/spec/data-model.md
- * § Capability-gated filters.
+ * Fail loud rather than silently widen or reorder: a filter or sort the
+ * adapter can't honor would otherwise be dropped, answering with some
+ * other result, which a caller reading one bounded page cannot detect.
+ * Every refusal names the capability. The companion to resolveQuery(),
+ * which refuses the query's own shape; every entry point runs both. See
+ * docs/spec/data-model.md § Capability-gated filters.
  */
-export declare function assertQueryCapabilities(filter: RecordFilter | undefined, capabilities: Pick<StackCapabilities, 'filter'>): void;
+export declare function assertQueryCapabilities(query: AdapterQuery, capabilities: Pick<StackCapabilities, 'filter' | 'sort'>): void;
+/**
+ * Hold `filter.contentByType` to a split along Types: at least one arm,
+ * each pinned to a TypeId and flat, and never beside a top-level content
+ * predicate, whose relation to the arms would be ambiguous. A map that
+ * could arrive empty would match everything once it crossed the wire. See
+ * docs/spec/data-model.md § Content by type.
+ */
+export declare function assertValidContentByType(filter: RecordFilter | undefined): void;
 /**
  * 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
@@ -42,101 +49,44 @@ export declare function filtersContent(features: Pick<StackCapabilities, 'filter
  */
 export declare function parseContentFilterKey(key: string): string[];
 /**
- * Reject a sort whose field or direction is outside the closed set the
- * types promise. `QuerySort` is typed `'asc' | 'desc'`, but a type is not a
- * runtime guard: a server mapping `?direction=` onto a query, or a
- * delegated app calling query(), supplies a raw string. A SQLite record
- * adapter interpolates the direction straight into `ORDER BY`, so an
- * unvalidated value there is a SQL-injection sink reachable from every
- * untrusted caller. Validating in the invariant layer — the same reason
- * emission and _config protection live here — means no adapter can forget
- * it. See docs/spec/data-model.md § Sorting and pagination.
+ * Reject a sort outside the closed set the types promise. A type is not a
+ * runtime guard, and a SQLite adapter interpolates the direction straight
+ * into `ORDER BY`, so an unvalidated one is an injection sink reachable by
+ * any untrusted caller. See docs/spec/data-model.md § Sorting and pagination.
  */
 export declare function assertValidSort(sort: QuerySort | undefined): void;
-/**
- * The sort every adapter receives: a named sort with no `direction` is
- * ascending, resolved here so no adapter carries its own default. No sort
- * stays absent — the adapter's unsorted order is `createdAt` newest first,
- * and an explicit sort would be re-checked against the server's declared
- * `sort.fields`. See docs/spec/data-model.md § Sorting and pagination.
- */
-export declare function normalizeSort(sort: QuerySort | undefined): (QuerySort & {
-    direction: 'asc' | 'desc';
-}) | undefined;
-/**
- * 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 declare function assertSortCapability(sort: QuerySort | undefined, capabilities: Pick<StackCapabilities, 'sort'>): void;
-/** Every key each relationship target arm defines. */
-export declare const TARGET_KEYS: Record<RelationshipTarget['kind'], readonly string[]>;
-/** Every key each grantee arm defines, the default tier included. */
-export declare const GRANTEE_KEYS: Record<GrantGrantee['kind'], readonly string[]>;
-/**
- * The keys of `value` its arm does not define. An element carrying one is
- * refused rather than stored: an adapter keeps only the keys it has
- * columns for, so the rest would answer 200 and then vanish.
- * See docs/spec/data-model.md § Associations.
- */
-export declare function unknownKeys(value: object, keys: readonly string[]): string[];
-/** unknownKeys() as a refusal. 400, not 422: the key addresses nothing. */
-export declare function assertKnownKeys(value: object, keys: readonly string[], path: string): void;
-/**
- * Reject a relationship target outside the closed set the types promise.
- * A discriminated union is not a runtime guard — a server mapping a
- * request body onto an association supplies raw JSON — and an
- * unrecognized kind would otherwise be stored under the one arm that
- * names a Record in this stack. See docs/spec/data-model.md
- * § Relationship targets.
- *
- * A key the element's kind does not define is thrown as a 400 rather than
- * collected, at every depth: it addresses nothing, the way an unknown key
- * on a request body does. See docs/spec/data-model.md § Associations.
- */
-export declare function validateAssociation(association: Association, path?: string): ValidationError[];
-/**
- * Refuse an authority element reaching the data half of the partition.
- * The two share a table, a delta shape and a durability tier; they never
- * share a call, because an app editing tags would otherwise be able to
- * replace an ACL it was never shown. Thrown rather than collected: the
- * caller named the wrong surface, not a malformed value, and the verb it
- * wanted is `grantAccess()`/`revokeAccess()`.
- *
- * Lives here, in the invariant layer, so an unscoped `Stack`, an import
- * and a server mapping a request body are all held to it.
- * See docs/spec/access-control.md § Record-level permissions.
- */
-export declare function assertDataAssociations(associations: readonly Association[], surface: string): asserts associations is DataAssociation[];
-/**
- * The mirror of assertDataAssociations(): the `permissions` surface takes
- * authority kinds alone, so a tag routed through it is refused rather than
- * quietly becoming an ACL entry the `associations` projection never shows.
- */
-export declare function assertAuthorityAssociations(permissions: readonly Association[], surface: string): asserts permissions is AuthorityAssociation[];
-/** validateAssociation() over a create's `associations` array. */
-/**
- * Every association in a list, plus the one rule a list has that a single
- * association does not: **identities are distinct**. A list naming one
- * identity twice describes a state no store can hold — an adapter keys
- * associations by identity, so the second entry displaces the first — and
- * which of the two the record ends up with is a question the caller did
- * not mean to ask. Refused rather than collapsed, for the reason an empty
- * change set is refused: every way of producing one is a caller bug.
- * See docs/spec/data-model.md § Associations.
- */
-export declare function validateAssociations(associations: Association[] | undefined, path?: string): ValidationError[];
-/**
- * Hold an association edit list to the rules every verb shares: non-empty,
- * every element a known `op` over a well-formed association, one surface,
- * and each identity named once — a list that both removes and adds one
- * identity is the same ambiguity as naming it twice. `repoint` is the
- * journal's word, never a request. Asked of the whole list before anything
- * is read or written. See docs/spec/data-model.md § Mutations.
- */
-export declare function assertAssociationEdits(changes: unknown, surface: string, half: 'data' | 'authority'): asserts changes is AssociationEdit[];
+/** The page a query reads when it names no `limit`. */
+export declare const DEFAULT_QUERY_LIMIT = 50;
+/** The largest page a query reads, whatever it asks for. */
+export declare const MAX_QUERY_LIMIT = 1000;
+/**
+ * The query an adapter receives: its shape checked, and every default
+ * resolved so no adapter carries one — a named sort runs ascending, no
+ * sort is `createdAt` newest first, and the page is DEFAULT_QUERY_LIMIT
+ * up to MAX_QUERY_LIMIT. Shape refusals name no capability; see
+ * assertQueryCapabilities() for those that do. See docs/spec/data-model.md
+ * § Sorting and pagination.
+ */
+export declare function resolveQuery(query: PlainQuery): AdapterQuery;
+/** A query split where it enters `Stack`; see splitQuery(). */
+export type SplitQuery = {
+    query: AdapterQuery;
+    presentAt?: StackQuery['presentAt'];
+};
+/**
+ * Split a query at the door into what an adapter sees, resolved, and
+ * `presentAt`, which `Stack` applies to the results. Every check runs
+ * here, before the adapter is asked. See docs/spec/data-model.md
+ * § Sorting and pagination.
+ */
+export declare function splitQuery(query: StackQuery): SplitQuery;
+/**
+ * Hold a window bound — a page size, a cursor position — to an integer
+ * at or above `min`, the one shape every adapter reads alike: a negative
+ * `limit` drops entries from a JS slice but empties or lifts a SQL
+ * `LIMIT`. See docs/spec/data-model.md § Sorting and pagination.
+ */
+export declare function assertWindowInteger(value: number | undefined, label: string, min: 0 | 1): void;
 /**
  * Reject an association filter that names neither of its halves, or whose
  * relationship target is malformed. `RelatedToFilter` and `AttachmentFilter`
@@ -145,6 +95,12 @@ export declare function assertAssociationEdits(changes: unknown, surface: string
  * any association of that kind. See docs/spec/data-model.md § Filter.
  */
 export declare function assertValidAssociationFilters(filter: RecordFilter | undefined): void;
+/**
+ * Refuse a `baseId` argument that cannot name a type family, as an
+ * argument error prefixed with the `surface` it was passed to. See
+ * familyIdProblem().
+ */
+export declare function assertFamilyId(baseId: unknown, surface: string): void;
 /**
  * Refuse a `baseId` carrying an `@version` suffix. A family filter resolves
  * against registered families, so a TypeId there would match nothing and
@@ -154,23 +110,14 @@ export declare function assertValidBaseIdFilter(filter: {
     baseId?: string | string[];
 } | undefined): void;
 /**
- * Hold a journal window to the shape both adapters can honor identically.
- *
- * Unvalidated, a negative `limit` diverges rather than failing: a JS
- * `slice(0, -1)` drops the newest entry, while SQLite reads a negative
- * LIMIT as "no ceiling" and returns the whole log. Neither is what the
- * caller asked for, and the disagreement is invisible until a stack
- * changes adapters. Refuse at the surface so no adapter has to guess.
- *
- * No ceiling is imposed: unlike a query, omitting `limit` reads the whole
- * log by contract, so a clamp would silently truncate exactly the caller
- * reconstructing an association's full history.
+ * A journal window: `afterSeq` 0 is the start of the log. No ceiling is
+ * imposed — omitting `limit` reads the whole log by contract, which a
+ * clamp would silently truncate.
  */
 export declare function assertValidJournalQuery(query: JournalQuery | undefined): void;
 /**
- * Refuse a `getVersions()` window the adapters would read differently, as
- * assertValidJournalQuery() does for the journal. No ceiling is imposed:
- * omitting `limit` reads every version by contract.
+ * A `getVersions()` window. No ceiling is imposed: omitting `limit` reads
+ * every version by contract.
  */
 export declare function assertValidVersionsQuery(query: VersionsQuery | undefined): void;
 //# sourceMappingURL=query-validation.d.ts.map

package/dist/query-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-validation.d.ts","sourceRoot":"","sources":["../src/query-validation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"query-validation.d.ts","sourceRoot":"","sources":["../src/query-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAYH,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EAEV,UAAU,EACV,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACd,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,YAAY,EACnB,YAAY,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,MAAM,CAAC,GACvD,IAAI,CAGN;AA0DD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI,CAgD/E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAC,GAAG,OAAO,CAEnF;AAUD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAqB3D;AAaD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI,CAsBjE;AAsDD,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,4DAA4D;AAC5D,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,YAAY,CAc5D;AAED,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;CACrC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAMxD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,CAO9F;AAmCD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI,CAmBpF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAKrE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CAAE,GAAG,SAAS,GAAG,IAAI,CAOhG;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI,CAG7E;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,CAG/E"}