@aglyn/plugins-data 1.0.0-beta.233 → 1.0.0-beta.235

package/src/lib/model/dataset-models.d.ts

@@ -15,6 +15,7 @@
  * limitations under the License.
  */
 import type { RepeatRowsModel } from '@aglyn/aglyn/app-utils/expand-repeatables';
+import { type DatasetFieldDefinition, type DatasetFilterValues, type DatasetModel } from './dataset-model-core';
 /**
  * Dataset models (AGL-177): the runtime promotion of the type-level
  * blueprint in `libs/shared/data/types/src/lib/dod.ts` (kept as the
@@ -31,92 +32,7 @@ import type { RepeatRowsModel } from '@aglyn/aglyn/app-utils/expand-repeatables'
  * numbers, coordinates as `{ latitude, longitude }`, `sorted` as arrays,
  * `map` as plain objects, references as target-document id strings.
  */
-/**
- * A human field entry from the quick creator: the stable id plus the
- * display name shown in table headers and bindings pickers (AGL-558).
- */
-export interface DatasetFieldEntry {
-    id: string;
-    name: string;
-}
-/** Display fallback for raw ids: "roast_preference" → "Roast preference". */
-export declare function humanizeDatasetFieldId(id: string): string;
-/** dod.ts `FT.Tag` vocabulary plus `reference` (AGL-180 builds on it). */
-export type DatasetFieldType = 'bool' | 'bytes' | 'timestamp' | 'float' | 'int32' | 'int64' | 'nil' | 'text' | 'coordinates' | 'map' | 'sorted' | 'reference';
-export declare const DATASET_FIELD_TYPES: DatasetFieldType[];
-/** Display names, mirroring dod.ts `lbl`. */
-export declare const DATASET_FIELD_TYPE_LABELS: Record<DatasetFieldType, string>;
-/**
- * Plain-JSON validation vocabulary (the dod.ts `Eval` shape, extended
- * with min/max and options, serialized flat instead of enum-keyed).
- */
-export interface DatasetFieldValidation {
-    required?: boolean;
-    /** Source of a RegExp applied to text values. */
-    regex?: string;
-    /** Numbers/timestamps: value bound. Text: length bound. */
-    min?: number;
-    max?: number;
-    /** Enum: value must be one of these (text fields). */
-    options?: string[];
-}
-export interface DatasetFieldDefinition {
-    /**
-     * Human-facing display label only. The stable reference id is the KEY in
-     * `DatasetModel.fields` (and `order`), NOT this name — bindings resolve
-     * `{{item.<fieldId>}}` against that key. The default id is derived from
-     * this name once at creation but is user-overridable (AGL-578); renaming
-     * the label afterwards never changes the id.
-     */
-    name: string;
-    type: DatasetFieldType;
-    /**
-     * Plugin-declared custom type riding this base type (AGL-434) — see
-     * plugin-manager/custom-fields. Unknown names degrade to the base type.
-     */
-    customType?: string;
-    /**
-     * A page-address field's source (AGL-3475): the field an EMPTY address
-     * fills in from, once — see `fillRecordAddresses` in `record-pages`.
-     * Meaningful only on a field of the page-address custom type.
-     */
-    slugFrom?: string;
-    description?: string;
-    required?: boolean;
-    /** Default applied by editors when creating documents; never coerced. */
-    default?: unknown;
-    validation?: DatasetFieldValidation;
-    /**
-     * Reference fields (AGL-180): target collection + display field id.
-     * `multiple` stores a `sorted` array of FKeys (small-cardinality
-     * many-to-many per the dod.ts guidance); `onDelete` is the referenced-
-     * document delete policy (default `setNull` — never cascade in v2).
-     */
-    reference?: {
-        datasetId: string;
-        displayFieldId?: string;
-        multiple?: boolean;
-        onDelete?: 'restrict' | 'setNull';
-    };
-}
-export interface DatasetModel {
-    fields: Record<string, DatasetFieldDefinition>;
-    /** Field ids in display order. */
-    order: string[];
-}
-/**
- * Migration shim (v1 → v2): datasets created before models carry flat
- * `fields: string[]` — derive a model where every column is an optional
- * text field whose id is the column name, so the editor and AGL-103
- * bindings keep working on unmigrated docs during rollout.
- */
-export declare function deriveModelFromFields(fields: string[]): DatasetModel;
-/**
- * Model from quick-creator entries (AGL-558): stable slug ids with the
- * human display names preserved — "Roast preference" → id
- * `roast_preference`, name "Roast preference".
- */
-export declare function modelFromFieldEntries(entries: readonly DatasetFieldEntry[]): DatasetModel;
+export * from './dataset-model-core';
 /**
  * The part of a dataset's model a repeat reads (AGL-180): each reference
  * field, by the id of the dataset it points into, which is a key the rows map
@@ -124,11 +40,6 @@ export declare function modelFromFieldEntries(entries: readonly DatasetFieldEntr
  * resolves wherever its target's rows were loaded.
  */
 export declare function repeatRowsModelOf(model: DatasetModel): RepeatRowsModel;
-/** The dataset's model, deriving one from v1 `fields` when absent. */
-export declare function effectiveDatasetModel(dataset: {
-    model?: DatasetModel;
-    fields?: string[];
-}): DatasetModel;
 /**
  * Validates a document's values against a model, returning fieldId →
  * human-readable error (empty object = valid). Values are expected in
@@ -136,14 +47,6 @@ export declare function effectiveDatasetModel(dataset: {
  * when starting from user input strings.
  */
 export declare function validateDocument(model: DatasetModel, values: Record<string, unknown>): Record<string, string>;
-/** Storage value → grid display string (AGL-179). */
-export declare function formatDatasetValue(field: DatasetFieldDefinition, value: unknown): string;
-/**
- * Storage value → form-input string (AGL-179): the inverse of
- * `coerceDocumentValues` for populating type-appropriate inputs
- * (timestamps as `datetime-local` values, coordinates as "lat, lon").
- */
-export declare function datasetValueToInput(field: DatasetFieldDefinition, value: unknown): string;
 /**
  * Whether a field stores a list: `sorted`, and a `reference` that may point at
  * more than one record. Both go through {@link coerceListValue}.
@@ -258,135 +161,3 @@ export declare function datasetIntegrityUpdate<TClear>(model: DatasetModel, valu
     filterKeys: string[] | TClear;
     filterValues: DatasetFilterValues | TClear;
 };
-/**
- * A dataset record's FILTER TOKENS: every word-level question the records
- * table can ask of a record, flattened into one array of strings Firestore
- * indexes on its own. Its twin, {@link datasetFilterValues}, holds the
- * equalities.
- *
- * ## Why these fields, and not the values
- *
- * A record's fields live under `values`, a user-defined, unbounded map that
- * the index configuration exempts from indexing — auto-indexing it can exceed
- * Firestore's per-document index-entry limit — so `where('values.<field>', …)`
- * is refused. A composite index per dataset would need an admin call per
- * dataset, runs into the project's composite-index cap, and is deleted by the
- * next `firestore:indexes` deploy of a file that does not list it.
- *
- * `filterKeys` and `filterValues` need none of that. Firestore's AUTOMATIC
- * single-field indexes serve `where('filterKeys', 'array-contains', token)`
- * and `where('filterValues.<field>', '==', value)`, and every automatic index
- * ends in the document name — so any number of those equalities and ONE
- * `array-contains`, under `orderBy(documentId())`, compose by index merging,
- * with no composite index and no index deploy, on any dataset of any project
- * (AGL-3321).
- *
- * ## The token grammar
- *
- *   `f:<fieldId>=<value>`   a field equals a value. Enum (a text field with
- *                           `validation.options`) values are kept exactly;
- *                           plain text is lower-cased, trimmed and clipped to
- *                           {@link DATASET_FILTER_VALUE_MAX} characters;
- *                           booleans are `true`/`false`; numbers are
- *                           `String(number)`; a `sorted` list contributes one
- *                           token per member.
- *   `f:<fieldId>^<prefix>`  a word of a plain text field starts with this.
- *   `s:<prefix>`            a word of ANY text value (enums and list members
- *                           included) starts with this — the quick search.
- *
- * Timestamps, references, maps, bytes, coordinates and nil fields carry no
- * field tokens: a timestamp is asked in ranges, which one token cannot serve,
- * and the rest are not asked about by value.
- *
- * The array is sorted, de-duplicated and capped at
- * {@link DATASET_FILTER_KEYS_MAX}. Past the cap, the `=` tokens are kept
- * first, then the per-field word prefixes, then the search prefixes, so a
- * very long record loses search reach before it loses exact matches.
- */
-export declare const DATASET_FILTER_KEYS_MAX = 500;
-/** Plain text values are clipped to this many characters in an `=` token. */
-export declare const DATASET_FILTER_VALUE_MAX = 64;
-/** Word prefixes run from 1 to this many characters. */
-export declare const DATASET_FILTER_PREFIX_MAX = 12;
-/** Only the first this-many words of a value contribute prefixes. */
-export declare const DATASET_FILTER_WORDS_MAX = 40;
-/** One clause of the records table's filter: `{ field, op, value }`. */
-export interface DatasetFilterClause {
-    field: string;
-    op: string;
-    value: string;
-}
-/**
- * The words of a text value: split on anything that is not a letter or a
- * digit, lower-cased, at most {@link DATASET_FILTER_WORDS_MAX} of them.
- */
-export declare function datasetFilterWords(text: string): string[];
-/**
- * Plain text as its stored key — its `=` token's value and its
- * `filterValues` entry: lower-cased, trimmed, clipped to
- * {@link DATASET_FILTER_VALUE_MAX} characters. What the records table asks a
- * typed value to equal.
- */
-export declare function datasetFilterTextKey(value: string): string;
-/** The tokens described in {@link DATASET_FILTER_KEYS_MAX}'s comment. */
-export declare function datasetFilterKeys(model: DatasetModel, values: Record<string, unknown> | undefined): string[];
-/** A record's `filterValues`: field id → the value an equality asks for. */
-export type DatasetFilterValues = Record<string, string | number | boolean>;
-/**
- * The query path of a field's `filterValues` entry, or null for a field id
- * no path can name — such a field is stamped no entry, and the records table
- * offers it no equality (its `contains`, served by `filterKeys`, stands).
- */
-export declare function datasetFilterValuePath(fieldId: string): string | null;
-/**
- * A dataset record's FILTER VALUES: `{ [fieldId]: value }`, one scalar per
- * field an equality can be asked of, so the records table puts every
- * equality on its query (AGL-3321).
- *
- *   enum text (`validation.options`)  the value exactly, as its `=` token;
- *   plain text                        {@link datasetFilterTextKey};
- *   bool                              a boolean;
- *   int32 / int64 / float             a number.
- *
- * A form or an automation stores every value as text, so `'19.50'` is the
- * number 19.5 and `'true'` the boolean, as in {@link datasetFilterKeys}.
- * Fields with no value, and timestamps, lists, references, maps, bytes,
- * coordinates and nil fields, carry no entry: a list is asked by member
- * (`f:<id>=<member>` in `filterKeys`), and the rest are not asked about by
- * value.
- *
- * ## What it costs
- *
- * Unlike `values`, this map is NOT exempt from indexing — that is its whole
- * point. Each entry is a scalar and costs two automatic index entries
- * (ascending, descending), so a record costs at most two per model field —
- * bounded by the model's field count (the `/v1` API caps a model at 100
- * fields), far inside Firestore's 40,000 entries per document, where
- * `values` was unbounded because a `map` or `sorted` value may hold anything.
- */
-export declare function datasetFilterValues(model: DatasetModel, values: Record<string, unknown> | undefined): DatasetFilterValues;
-/**
- * The `filterKeys` token a word-level clause asks for, or null when it is
- * not one:
- *
- *  - plain text `contains` → the `^` token of the value's FIRST word, so a
- *    `contains` is a word-prefix match, not a mid-string one, and one word
- *    of several is asked (the records table says so);
- *  - list `contains` (and `equals`) → the member's `=` token;
- *  - enum, boolean, number and plain text `equals` → the `=` token of the
- *    value. The records table asks these of `filterValues` instead, which
- *    composes with a `contains`; the token remains what the quick search and
- *    older readers match.
- *  - everything else — ranges, dates, `isEmpty`, `isAnyOf`, negations — null.
- *
- * `clause.field` is the field id. The operator names are the grid's: a
- * select's `equals`, a number's `=`, a boolean's `is`, a list's `contains`.
- */
-export declare function datasetFilterToken(model: DatasetModel, clause: DatasetFilterClause): string | null;
-/**
- * The quick-search token for one typed word, or null for a word with no
- * letters or digits. A word with punctuation inside it is asked by its first
- * run — split the search text with {@link datasetFilterWords} to ask for
- * every run.
- */
-export declare function datasetSearchToken(word: string): string | null;