vintasend-managed-templates 1.0.0-alpha2

package/dist/errors.js

@@ -0,0 +1,86 @@
+/**
+ * Every failure this package reports, as a class a caller can branch on.
+ *
+ * `instanceof` works across the whole hierarchy because each constructor restores the prototype
+ * chain — TypeScript compiled to an ES5-era target breaks it otherwise, and this package is
+ * consumed by applications that pick their own target.
+ */
+export class ManagedTemplateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Raised when a template is not found in the backend. */
+export class ManagedTemplateNotFoundError extends ManagedTemplateError {
+}
+/** Raised when a filter is malformed or names a field the vocabulary does not have. */
+export class ManagedTemplateInvalidFilterError extends ManagedTemplateError {
+}
+/**
+ * Raised when a listing asks for an order the configured backend cannot apply.
+ *
+ * This throws rather than quietly dropping the order, which is the difference between ordering
+ * and filtering: a dropped filter returns more rows than asked for, which a caller can see, while
+ * a dropped order returns the same rows in an arbitrary sequence that looks sorted. Read
+ * `getBackendSupportedFilterCapabilities()` and offer only the fields it reports.
+ */
+export class ManagedTemplateUnsupportedOrderingError extends ManagedTemplateError {
+}
+/** Raised when a status change is attributed to a user the backend cannot resolve. */
+export class ManagedTemplateChangeUserNotFoundError extends ManagedTemplateError {
+}
+/** Raised when a status change is not allowed from the version's current status. */
+export class ManagedTemplateStatusTransitionError extends ManagedTemplateError {
+}
+/** Raised when a tag is not found in the backend. */
+export class ManagedTemplateTagNotFoundError extends ManagedTemplateError {
+}
+/** Raised when creating a tag whose text already slugs onto an existing tag. */
+export class ManagedTemplateTagAlreadyExistsError extends ManagedTemplateError {
+}
+/** Raised when a tag's text is empty or has nothing that can be slugified. */
+export class ManagedTemplateInvalidTagError extends ManagedTemplateError {
+}
+/**
+ * Base class for every failure of {@link TemplateComposer}.
+ *
+ * Composition runs before the template engine does, so nothing here can be caught (or reported)
+ * by the engine downstream. Catch this to treat "the template could not be assembled" as one
+ * condition, or a subclass to tell a typo apart from a missing base.
+ */
+export class ManagedTemplateCompositionError extends ManagedTemplateError {
+}
+/** Raised when a `managed_*` composition tag is malformed, unknown or unbalanced. */
+export class ManagedTemplateCompositionSyntaxError extends ManagedTemplateCompositionError {
+}
+/**
+ * Raised when a template extends or includes a template that does not exist.
+ *
+ * The Python sibling makes this a `ManagedTemplateNotFoundError` as well, so code already
+ * handling a missing template keeps working. TypeScript has no multiple inheritance, so the
+ * relationship is carried by {@link isNotFoundError} instead — check with that rather than with
+ * a bare `instanceof ManagedTemplateNotFoundError`, and test for
+ * `ManagedTemplateCompositionError` *before* "not found" wherever the distinction matters: a
+ * base that does not exist is a broken composition of a template that does.
+ */
+export class ManagedTemplateCompositionReferenceError extends ManagedTemplateCompositionError {
+}
+/** Raised when a chain of extends/include references comes back to where it started. */
+export class ManagedTemplateCompositionCycleError extends ManagedTemplateCompositionError {
+}
+/** Raised when a chain of references runs deeper than the composer's `maxDepth`. */
+export class ManagedTemplateCompositionDepthError extends ManagedTemplateCompositionError {
+}
+/**
+ * Whether an error means "the thing you asked for is not in the store".
+ *
+ * True for {@link ManagedTemplateNotFoundError} and for
+ * {@link ManagedTemplateCompositionReferenceError}, which is a missing template reached through
+ * a template that exists.
+ */
+export function isNotFoundError(error) {
+    return (error instanceof ManagedTemplateNotFoundError ||
+        error instanceof ManagedTemplateCompositionReferenceError);
+}

package/dist/filter-evaluation.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Evaluating a `ManagedTemplateFilter` against templates already in hand.
+ *
+ * Not every store can push every filter down. A SQL backend can; a FHIR one cannot express `or`
+ * at all, and a document store may have no way to ask "does this row carry all of these tags".
+ * Rather than have each of those backends re-derive what a filter means — and disagree with the
+ * others on the corners — this module is the one implementation of the semantics, and a backend
+ * narrows server-side as far as it can and finishes here.
+ *
+ * That makes the fallback sound by construction: whatever a backend's query language can express
+ * is an optimization, and what it cannot express is still answered correctly.
+ */
+import { type ManagedTemplateStatus } from './constants.js';
+import { type DateRange, type IntegerFieldFilter, type ManagedTemplateFilter, type ManagedTemplateOrderBy, type ManagedTemplateStatusFilter, type StringFieldFilter } from './filters.js';
+import type { ManagedTemplate } from './types.js';
+export type FilterEvaluationContext = {
+    /**
+     * Every version of one key, needed only by `mostRecentActiveVersion` — the one field whose
+     * answer depends on the *other* rows in the store rather than on the row being tested.
+     *
+     * A filter that names that field without this available cannot be answered, so
+     * {@link matchesTemplateFilter} throws rather than guessing.
+     */
+    versionsOfKey?: (key: string) => readonly ManagedTemplate[];
+};
+export declare function matchesString(value: string, filter: StringFieldFilter): boolean;
+export declare function matchesInteger(value: number, filter: IntegerFieldFilter): boolean;
+export declare function matchesStatus(value: ManagedTemplateStatus, filter: ManagedTemplateStatusFilter): boolean;
+/**
+ * Whether a date falls in a range.
+ *
+ * A row whose date is unset never matches a positive range — the same NULL rule `vintasend`'s
+ * notification date ranges follow — but `createdAt` and `updatedAt` are always set on a stored
+ * template, so this only comes up for a template assembled by hand.
+ */
+export declare function matchesDateRange(value: Date | null | undefined, range: DateRange): boolean;
+/**
+ * Whether a row is its key's current version.
+ *
+ * "This row is active or draft, and no active-or-draft row of the same key is numbered higher."
+ * Written as a comparison against the key's other versions rather than as a lookup, because that
+ * is what the field means — see `ManagedTemplateFilterFields.mostRecentActiveVersion`.
+ */
+export declare function isMostRecentActiveVersion(template: ManagedTemplate, versions: readonly ManagedTemplate[]): boolean;
+/** Whether one template satisfies a filter, groups and all. */
+export declare function matchesTemplateFilter(template: ManagedTemplate, filter: ManagedTemplateFilter, context?: FilterEvaluationContext): boolean;
+/**
+ * Slugify a filter's tag values, dropping the ones that name no tag.
+ *
+ * A caller may name a tag by its slug or by the text behind it, so this is what makes
+ * `includesAllTags: ['Black Friday']` and `includesAllTags: ['black-friday']` the same query.
+ */
+export declare function normalizeSlugs(tags: readonly string[]): string[];
+/** Slice a 1-indexed page out of a complete, ordered result set. */
+/**
+ * Order templates by one field, for a backend whose store cannot do it.
+ *
+ * Sorting in memory is only correct over a **complete** result set — sort a page and you order
+ * rows within it while the rows chosen for it came back in the store's own order. So this is for
+ * a backend that reads everything anyway, and such a backend must still report `orderBy.*`
+ * honestly: it can sort, so it says `true`.
+ *
+ * The sort is total and stable. Every field falls back to `(key, version)` on a tie, so two rows
+ * that compare equal on the named field still come back in the same order on every call — a page
+ * boundary that moves between two requests silently drops or repeats rows.
+ */
+export declare function sortTemplates(templates: readonly ManagedTemplate[], orderBy: ManagedTemplateOrderBy | undefined): ManagedTemplate[];
+export declare function paginate<Row>(rows: readonly Row[], page: number, pageSize: number): Row[];
+//# sourceMappingURL=filter-evaluation.d.ts.map

package/dist/filter-evaluation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-evaluation.d.ts","sourceRoot":"","sources":["../src/filter-evaluation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,qBAAqB,EAAuC,MAAM,gBAAgB,CAAC;AACjG,OAAO,EACL,KAAK,SAAS,EACd,KAAK,kBAAkB,EAMvB,KAAK,qBAAqB,EAE1B,KAAK,sBAAsB,EAC3B,KAAK,2BAA2B,EAChC,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,eAAe,EAAE,CAAC;CAC7D,CAAC;AAEF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAmB/E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAcjF;AAED,wBAAgB,aAAa,CAC3B,KAAK,EAAE,qBAAqB,EAC5B,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAQT;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAW1F;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,SAAS,eAAe,EAAE,GACnC,OAAO,CAUT;AAED,+DAA+D;AAC/D,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,qBAAqB,EAC7B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAWT;AAyED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAEhE;AAED,oEAAoE;AACpE;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,SAAS,eAAe,EAAE,EACrC,OAAO,EAAE,sBAAsB,GAAG,SAAS,GAC1C,eAAe,EAAE,CAwBnB;AAuDD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,EAAE,CAGzF"}

package/dist/filter-evaluation.js

@@ -0,0 +1,252 @@
+/**
+ * Evaluating a `ManagedTemplateFilter` against templates already in hand.
+ *
+ * Not every store can push every filter down. A SQL backend can; a FHIR one cannot express `or`
+ * at all, and a document store may have no way to ask "does this row carry all of these tags".
+ * Rather than have each of those backends re-derive what a filter means — and disagree with the
+ * others on the corners — this module is the one implementation of the semantics, and a backend
+ * narrows server-side as far as it can and finishes here.
+ *
+ * That makes the fallback sound by construction: whatever a backend's query language can express
+ * is an optimization, and what it cannot express is still answered correctly.
+ */
+import { MOST_RECENT_ACTIVE_VERSION_STATUSES } from './constants.js';
+import { isFieldFilter, isNumericFilterLookup, isStatusExactLookup, isStatusInLookup, isStringFilterLookup, } from './filters.js';
+import { slugifyTag } from './tags.js';
+export function matchesString(value, filter) {
+    if (!isStringFilterLookup(filter)) {
+        return value === filter;
+    }
+    const caseSensitive = filter.caseSensitive ?? true;
+    const haystack = caseSensitive ? value : value.toLowerCase();
+    const needle = caseSensitive ? filter.value : filter.value.toLowerCase();
+    switch (filter.lookup) {
+        case 'exact':
+            return haystack === needle;
+        case 'startsWith':
+            return haystack.startsWith(needle);
+        case 'endsWith':
+            return haystack.endsWith(needle);
+        case 'includes':
+            return haystack.includes(needle);
+    }
+}
+export function matchesInteger(value, filter) {
+    if (!isNumericFilterLookup(filter)) {
+        return value === filter;
+    }
+    switch (filter.lookup) {
+        case 'gt':
+            return value > filter.value;
+        case 'gte':
+            return value >= filter.value;
+        case 'lt':
+            return value < filter.value;
+        case 'lte':
+            return value <= filter.value;
+    }
+}
+export function matchesStatus(value, filter) {
+    if (isStatusInLookup(filter)) {
+        return filter.value.includes(value);
+    }
+    if (isStatusExactLookup(filter)) {
+        return value === filter.value;
+    }
+    return value === filter;
+}
+/**
+ * Whether a date falls in a range.
+ *
+ * A row whose date is unset never matches a positive range — the same NULL rule `vintasend`'s
+ * notification date ranges follow — but `createdAt` and `updatedAt` are always set on a stored
+ * template, so this only comes up for a template assembled by hand.
+ */
+export function matchesDateRange(value, range) {
+    if (!(value instanceof Date)) {
+        return false;
+    }
+    if (range.from !== undefined && value.getTime() < range.from.getTime()) {
+        return false;
+    }
+    if (range.to !== undefined && value.getTime() > range.to.getTime()) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Whether a row is its key's current version.
+ *
+ * "This row is active or draft, and no active-or-draft row of the same key is numbered higher."
+ * Written as a comparison against the key's other versions rather than as a lookup, because that
+ * is what the field means — see `ManagedTemplateFilterFields.mostRecentActiveVersion`.
+ */
+export function isMostRecentActiveVersion(template, versions) {
+    if (!MOST_RECENT_ACTIVE_VERSION_STATUSES.includes(template.status)) {
+        return false;
+    }
+    return !versions.some((candidate) => candidate.key === template.key &&
+        MOST_RECENT_ACTIVE_VERSION_STATUSES.includes(candidate.status) &&
+        candidate.version > template.version);
+}
+/** Whether one template satisfies a filter, groups and all. */
+export function matchesTemplateFilter(template, filter, context = {}) {
+    if (!isFieldFilter(filter)) {
+        if ('and' in filter) {
+            return filter.and.every((sub) => matchesTemplateFilter(template, sub, context));
+        }
+        if ('or' in filter) {
+            return filter.or.some((sub) => matchesTemplateFilter(template, sub, context));
+        }
+        return !matchesTemplateFilter(template, filter.not, context);
+    }
+    return matchesFields(template, filter, context);
+}
+function matchesFields(template, filters, context) {
+    if (filters.name !== undefined && !matchesString(template.name, filters.name)) {
+        return false;
+    }
+    if (filters.description !== undefined &&
+        !matchesString(template.description, filters.description)) {
+        return false;
+    }
+    if (filters.key !== undefined && !matchesString(template.key, filters.key)) {
+        return false;
+    }
+    if (filters.templateManagedBackend !== undefined &&
+        !matchesString(template.templateManagedBackend, filters.templateManagedBackend)) {
+        return false;
+    }
+    if (filters.version !== undefined && !matchesInteger(template.version, filters.version)) {
+        return false;
+    }
+    if (filters.status !== undefined && !matchesStatus(template.status, filters.status)) {
+        return false;
+    }
+    if (filters.createdAtRange !== undefined &&
+        !matchesDateRange(template.createdAt, filters.createdAtRange)) {
+        return false;
+    }
+    if (filters.updatedAtRange !== undefined &&
+        !matchesDateRange(template.updatedAt, filters.updatedAtRange)) {
+        return false;
+    }
+    if (filters.includesAllTags !== undefined) {
+        const carried = new Set(template.tags.map((tag) => tag.slug));
+        if (!normalizeSlugs(filters.includesAllTags).every((slug) => carried.has(slug))) {
+            return false;
+        }
+    }
+    if (filters.includesAnyOfTags !== undefined) {
+        const carried = new Set(template.tags.map((tag) => tag.slug));
+        if (!normalizeSlugs(filters.includesAnyOfTags).some((slug) => carried.has(slug))) {
+            return false;
+        }
+    }
+    if (filters.isAbstract !== undefined && template.isAbstract !== filters.isAbstract) {
+        return false;
+    }
+    if (filters.mostRecentActiveVersion !== undefined) {
+        if (context.versionsOfKey === undefined) {
+            throw new Error("mostRecentActiveVersion is answered against a key's other versions, so " +
+                'matchesTemplateFilter needs a versionsOfKey lookup to evaluate it.');
+        }
+        const current = isMostRecentActiveVersion(template, context.versionsOfKey(template.key));
+        if (current !== filters.mostRecentActiveVersion) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Slugify a filter's tag values, dropping the ones that name no tag.
+ *
+ * A caller may name a tag by its slug or by the text behind it, so this is what makes
+ * `includesAllTags: ['Black Friday']` and `includesAllTags: ['black-friday']` the same query.
+ */
+export function normalizeSlugs(tags) {
+    return tags.map((tag) => slugifyTag(tag)).filter(Boolean);
+}
+/** Slice a 1-indexed page out of a complete, ordered result set. */
+/**
+ * Order templates by one field, for a backend whose store cannot do it.
+ *
+ * Sorting in memory is only correct over a **complete** result set — sort a page and you order
+ * rows within it while the rows chosen for it came back in the store's own order. So this is for
+ * a backend that reads everything anyway, and such a backend must still report `orderBy.*`
+ * honestly: it can sort, so it says `true`.
+ *
+ * The sort is total and stable. Every field falls back to `(key, version)` on a tie, so two rows
+ * that compare equal on the named field still come back in the same order on every call — a page
+ * boundary that moves between two requests silently drops or repeats rows.
+ */
+export function sortTemplates(templates, orderBy) {
+    const rows = [...templates];
+    if (orderBy === undefined) {
+        return rows;
+    }
+    const sign = orderBy.direction === 'desc' ? -1 : 1;
+    return rows.sort((left, right) => {
+        // Absent values sort last in *both* directions, so this is compared before the sign is
+        // applied. `createdAt` and `updatedAt` are typed non-null, but a backend hydrating them from
+        // a store that allows null would otherwise put its nulls first on `desc` and last on `asc`.
+        const nullness = compareNullness(left, right, orderBy.field);
+        if (nullness !== 0) {
+            return nullness;
+        }
+        const primary = compareField(left, right, orderBy.field);
+        if (primary !== 0) {
+            return primary * sign;
+        }
+        // The tiebreak is *not* reversed either: it exists to make the order total, and flipping it
+        // with the direction would make `asc` and `desc` disagree on which of two equal rows comes
+        // first — which is how a page boundary starts dropping and repeating rows.
+        return compareTiebreak(left, right);
+    });
+}
+/** -1, 0 or 1 according to which side is missing a value for `field`; 0 when both have one. */
+function compareNullness(left, right, field) {
+    const leftMissing = (left[field] ?? null) === null;
+    const rightMissing = (right[field] ?? null) === null;
+    if (leftMissing === rightMissing)
+        return 0;
+    return leftMissing ? 1 : -1;
+}
+function compareField(left, right, field) {
+    switch (field) {
+        case 'key':
+            return compareStrings(left.key, right.key);
+        case 'name':
+            return compareStrings(left.name, right.name);
+        case 'status':
+            return compareStrings(left.status, right.status);
+        case 'version':
+            return left.version - right.version;
+        case 'createdAt':
+            return compareDates(left.createdAt, right.createdAt);
+        case 'updatedAt':
+            return compareDates(left.updatedAt, right.updatedAt);
+    }
+}
+function compareTiebreak(left, right) {
+    return compareStrings(left.key, right.key) || left.version - right.version;
+}
+/**
+ * Compare by code point rather than by locale.
+ *
+ * `localeCompare` would order rows differently depending on where the process runs, which for a
+ * paginated read means two pages of the same listing served by two machines can disagree.
+ */
+function compareStrings(left, right) {
+    if (left === right)
+        return 0;
+    return left < right ? -1 : 1;
+}
+/** Only reached with two present values — `compareNullness` has already settled the rest. */
+function compareDates(left, right) {
+    return (left?.getTime() ?? 0) - (right?.getTime() ?? 0);
+}
+export function paginate(rows, page, pageSize) {
+    const start = (page - 1) * pageSize;
+    return rows.slice(start, start + pageSize);
+}

package/dist/filters.d.ts

@@ -0,0 +1,192 @@
+/**
+ * The filter vocabulary a template-manager backend evaluates.
+ *
+ * Spelled exactly the way `vintasend` spells its notification filters — camelCase fields,
+ * camelCase string lookups (`startsWith`, not `starts_with`), a `DateRange` with `from`/`to`,
+ * and the same `and`/`or`/`not` grouping — so a caller that already builds one kind of filter
+ * needs no second set of rules for this one.
+ */
+import type { ManagedTemplateStatus } from './constants.js';
+/** Date range filter with optional lower and upper bounds. */
+export type DateRange = {
+    from?: Date;
+    to?: Date;
+};
+export type StringFilterLookup = {
+    lookup: 'exact' | 'startsWith' | 'endsWith' | 'includes';
+    value: string;
+    caseSensitive?: boolean;
+};
+/** A bare string is a case-sensitive `exact` match. */
+export type StringFieldFilter = string | StringFilterLookup;
+export type NumericFilterLookup = {
+    lookup: 'gt' | 'gte' | 'lt' | 'lte';
+    value: number;
+};
+export type IntegerFieldFilter = number | NumericFilterLookup;
+export type ManagedTemplateStatusFilter = ManagedTemplateStatus | {
+    lookup: 'exact';
+    value: ManagedTemplateStatus;
+} | {
+    lookup: 'in';
+    value: ManagedTemplateStatus[];
+};
+/**
+ * A tag filter is a plain list of tag slugs — no lookup wrapper, because which of the two
+ * matches is meant is already said by the field name (`includesAllTags` / `includesAnyOfTags`)
+ * rather than by a `lookup` key.
+ *
+ * Values are matched against `ManagedTemplateTag.slug`. Backends slugify what they are given
+ * first, so a caller may pass either the slug or the text it came from and get the same result.
+ */
+export type TagsFieldFilter = string[];
+/**
+ * Leaf-level filter conditions. Every field present is combined with implicit AND.
+ */
+export type ManagedTemplateFilterFields = {
+    name?: StringFieldFilter;
+    description?: StringFieldFilter;
+    key?: StringFieldFilter;
+    version?: IntegerFieldFilter;
+    templateManagedBackend?: StringFieldFilter;
+    status?: ManagedTemplateStatusFilter;
+    createdAtRange?: DateRange;
+    updatedAtRange?: DateRange;
+    /**
+     * Tag membership. `includesAllTags` matches a template carrying every listed tag,
+     * `includesAnyOfTags` one carrying at least one of them. Both follow `Array.every` /
+     * `Array.some` on an empty list: an empty `includesAllTags` constrains nothing, an empty
+     * `includesAnyOfTags` matches nothing.
+     */
+    includesAllTags?: TagsFieldFilter;
+    includesAnyOfTags?: TagsFieldFilter;
+    /**
+     * Bases, or templates to send. `true` keeps only the templates that declare a
+     * `{% managed_children %}` hole or blocks without extending anything; `false` keeps only the
+     * ones that do not.
+     *
+     * Answered against the stored `ManagedTemplate.isAbstract` — a field a backend writes on
+     * every write — rather than by parsing sources at query time, which is the whole reason the
+     * flag is denormalized: a picker that has to exclude bases would otherwise read and parse
+     * every row in the store to draw one page.
+     */
+    isAbstract?: boolean;
+    /**
+     * One row per key instead of one row per version. `true` keeps, for each key, only the
+     * highest-numbered version whose status is in `MOST_RECENT_ACTIVE_VERSION_STATUSES` (`active`
+     * or `draft`), and drops every key with no such version. `false` is its exact complement —
+     * every other row, retired keys included — so it is what `{ not: { mostRecentActiveVersion:
+     * true } }` means.
+     *
+     * This is the one field whose answer depends on the *other* rows in the store rather than on
+     * the row being tested, so a backend evaluates it against the whole key, not the row.
+     */
+    mostRecentActiveVersion?: boolean;
+};
+export type ManagedTemplateFilter = ManagedTemplateFilterFields | {
+    and: ManagedTemplateFilter[];
+} | {
+    or: ManagedTemplateFilter[];
+} | {
+    not: ManagedTemplateFilter;
+};
+/**
+ * The fields `ManagedTemplateFilterFields` accepts, as data.
+ *
+ * Kept in step with the type by {@link ManagedTemplateFilterFieldName}, which fails to compile
+ * if the two drift apart — a field added to the type without a name here is a type error rather
+ * than a filter the service silently rejects.
+ */
+export declare const KNOWN_FILTER_FIELDS: readonly ["name", "description", "key", "version", "templateManagedBackend", "status", "createdAtRange", "updatedAtRange", "includesAllTags", "includesAnyOfTags", "isAbstract", "mostRecentActiveVersion"];
+/** The filter fields whose value is a list of tag slugs rather than a lookup object. */
+export declare const TAG_FILTER_FIELDS: readonly ["includesAllTags", "includesAnyOfTags"];
+/** The filter fields whose value is a bare boolean. */
+export declare const FLAG_FILTER_FIELDS: readonly ["mostRecentActiveVersion", "isAbstract"];
+/** True when `filter` is a field filter rather than an `and`/`or`/`not` group. */
+export declare function isFieldFilter(filter: ManagedTemplateFilter): filter is ManagedTemplateFilterFields;
+/** True when a string-field filter is a `StringFilterLookup` and not a bare string. */
+export declare function isStringFilterLookup(value: unknown): value is StringFilterLookup;
+export declare function isNumericFilterLookup(value: unknown): value is NumericFilterLookup;
+export declare function isDateRange(value: unknown): value is DateRange;
+export declare function isStatusInLookup(value: unknown): value is {
+    lookup: 'in';
+    value: ManagedTemplateStatus[];
+};
+export declare function isStatusExactLookup(value: unknown): value is {
+    lookup: 'exact';
+    value: ManagedTemplateStatus;
+};
+/**
+ * True when a value is a list of tag slugs.
+ *
+ * A bare string is deliberately rejected: `{ includesAllTags: 'welcome' }` would otherwise be
+ * spread character by character by a backend that iterates it, and silently ask for the tags
+ * `w`, `e`, `l`. Pass a one-element array instead.
+ */
+export declare function isTagsFilter(value: unknown): value is TagsFieldFilter;
+/**
+ * Which filters a template-manager backend can honour.
+ *
+ * Follows the same rule as `vintasend`'s notification capabilities: **a backend declares only
+ * what it cannot do.** Its report is merged *over* an all-`true` default, so a filter field
+ * added in a later release does not force every backend to re-declare support for it, and a
+ * missing key means "supported".
+ *
+ * `orderBy.*` keys report which fields a backend can sort a page by. They are new vocabulary, so
+ * they default to **false**: a backend that predates ordering ignores the argument, and claiming
+ * an order it does not apply is worse than admitting it cannot — a caller that knows gets to
+ * decide, while one that is lied to silently renders rows in an arbitrary order and calls it
+ * sorted.
+ *
+ * Ordering has to reach the store rather than being applied to the page afterwards. Sorting a
+ * page after the fact orders rows *within* the page while the rows chosen *for* it stayed in the
+ * backend's own order, which looks right on page 1 and is wrong everywhere after it.
+ */
+export type ManagedTemplateFilterCapabilities = {
+    [key: string]: boolean;
+};
+/**
+ * The fields a template listing can be ordered by.
+ *
+ * Deliberately narrow: each one is a scalar the backend already stores per row, so a store can
+ * answer it with an index rather than a computed sort. `tags` is absent because ordering by a
+ * many-to-many has no single value to compare, and `mostRecentActiveVersion` because it is a
+ * filter rather than a field.
+ */
+export type ManagedTemplateOrderByField = 'key' | 'name' | 'version' | 'status' | 'createdAt' | 'updatedAt';
+export type ManagedTemplateOrderDirection = 'asc' | 'desc';
+export type ManagedTemplateOrderBy = {
+    field: ManagedTemplateOrderByField;
+    direction: ManagedTemplateOrderDirection;
+};
+/** Every orderable field, for validation and for building a capability report. */
+export declare const MANAGED_TEMPLATE_ORDER_BY_FIELDS: readonly ManagedTemplateOrderByField[];
+/** The capability key reporting whether a backend can order by `field`. */
+export declare function orderByCapabilityKey(field: ManagedTemplateOrderByField): string;
+export declare const DEFAULT_TEMPLATE_BACKEND_FILTER_CAPABILITIES: ManagedTemplateFilterCapabilities;
+/**
+ * Drop the parts of a filter the backend has declared it cannot answer.
+ *
+ * This is the other half of the capability report: reporting a limitation is only useful if
+ * something acts on it. Every caller that builds a filter would otherwise have to walk the
+ * capability map itself and reach its own conclusions, and they would disagree.
+ *
+ * **Dropping widens.** A pruned filter matches everything the original did and possibly more, so
+ * a caller sees extra rows rather than missing ones — a listing that could not collapse to one
+ * row per key shows every version, which is visible in the result. That is the whole reason
+ * filters are negotiated by dropping while *ordering* is negotiated by refusing: an ignored order
+ * leaves no trace in the rows at all. Check the report before trusting a filter to have narrowed.
+ *
+ * Returns an empty filter — which constrains nothing — when everything has been dropped.
+ */
+export declare function pruneUnsupportedFilters(filter: ManagedTemplateFilter, capabilities: ManagedTemplateFilterCapabilities): ManagedTemplateFilter;
+/** True for a filter that constrains nothing, whatever shape it arrived in. */
+export declare function isEmptyFilter(filter: ManagedTemplateFilter): boolean;
+/**
+ * Read one capability, defaulting to supported.
+ *
+ * A missing key means "supported": backends declare only what they *cannot* do, so a capability
+ * added in a later release does not force every backend to re-declare it.
+ */
+export declare function supportsCapability(capabilities: ManagedTemplateFilterCapabilities, key: string): boolean;
+//# sourceMappingURL=filters.d.ts.map

package/dist/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../src/filters.ts"],"names":[],"mappings":"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"}