@aglyn/shared-data-types 1.0.0-beta.143

package/src/lib/dod.d.ts

@@ -0,0 +1,345 @@
+/**
+ * @license
+ * Copyright 2023 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * (D)Document-(o)oriented (D)Database (DoD)
+ *
+ * A document-oriented database, or DoD, or document
+ * store, is a data storage structure designed for
+ * storing, retrieving and managing document-oriented
+ * information, also known as semi-structured data.
+ *
+ * Each document contains a set of key-value pairs.
+ * All documents must be stored in collections.
+ *
+ * Documents can contain literal fields such as
+ * text/strings, numbers, or booleans, and secondly
+ * nestable fields such as arrays or mapped objects.
+ *
+ * The special sauce here which deviates from a
+ * traditional DoD is the overlaid design patterns
+ * which provide the outlines for capabilities such
+ * as relational- and model-driven
+ *
+ * @module dod
+ */
+/** Primary key */
+export type PKey = string;
+/** Foreign key */
+export type FKey = string;
+/** Alternate key */
+export type AKey = string;
+/** Tuple with exactly two nodes */
+export interface TupleLn2<T1, T2 = T1> extends Array<T1 | T2> {
+    0: T1;
+    1: T2;
+    length: 2;
+}
+/** Tuple with a minimum of one nodes */
+interface TupleMinLn1<T> extends Array<T> {
+    0: T;
+}
+/** Tuple with a minimum of two nodes */
+interface TupleMinLn2<T1, T2 = T1> extends TupleMinLn1<T1 | T2> {
+    0: T1;
+    1: T2;
+}
+/**
+ * Nominal Type hack to declare a typeof type for
+ * a unique symbol. This is because `unique symbol`
+ * can only be typed from a const.
+ *
+ * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-7.html#unique-symbol
+ */
+declare const NominalSymbol: unique symbol;
+export type UniqSym = typeof NominalSymbol;
+/**
+ * Describes relationship design patterns to
+ * outline a RDBMS equivalent
+ */
+export declare namespace Relation {
+    /**
+     * A associative lookup for unnatural/extrinsic
+     * Many-to-Many relationship.
+     *
+     * Note: intrinsic 2-way relations should live within
+     * both documents and not use an extra query/join for
+     * the lookup! However, a rare scenario that it is too
+     * large, you may store the most recent (n) items in
+     * the two documents and use the lookup for the rest.
+     *
+     * Consider the following 2-way relationship:
+     * group1 = [user1, user3]
+     * group2 = [user1, user2]
+     * group3 = [user2, user3]
+     * user1 = [group1, group2]
+     * user2 = [group2, group3]
+     * user3 = [group1, group3]
+     *
+     * That would be displayed in an associative as follows:
+     * AK1 = [group1, user1]
+     * AK2 = [group1, user3]
+     * AK3 = [group2, user1]
+     * AK4 = [group2, user2]
+     * AK5 = [group3, user2]
+     * AK6 = [group3, user3]
+     */
+    type Associative = TupleLn2<FKey>;
+    /**
+     * Similar to an associative relation but rather to
+     * find many associations
+     *
+     * e.g. Invoice, Product, User lookups
+     * AK1 = [invoiceId, productId, userId]
+     */
+    type Lookup = TupleMinLn2<FKey>;
+}
+/** Field Type */
+export declare namespace FT {
+    type Bool = boolean;
+    type Bytes = Uint8Array | string;
+    type Timestamp = number;
+    type Float = number;
+    type Int32 = number;
+    type Int64 = number;
+    type Null = null;
+    type Text = string;
+    type Coordinates = Record<'longitude' | 'latitude', number>;
+    type Map = Dictionary;
+    type Sorted<T = any> = T extends any[] ? never : T[];
+    type Nestable = Map | Sorted<any>;
+    type Any<T = any> = Sorted<T> | Bool | Bytes | Timestamp | Float | Coordinates | Int32 | Int64 | Map | Null | Text;
+    namespace Tag {
+        const bool = "bool";
+        const bytes = "bytes";
+        const timestamp = "timestamp";
+        const float = "float";
+        const int32 = "int32";
+        const int64 = "int64";
+        const nil = "nil";
+        const text = "text";
+        const coordinates = "coordinates";
+        const map = "map";
+        const sorted = "sorted";
+        const all: string[];
+        type T = typeof Tag.bool | typeof Tag.bytes | typeof Tag.timestamp | typeof Tag.float | typeof Tag.int32 | typeof Tag.int64 | typeof Tag.nil | typeof Tag.text | typeof Tag.coordinates | typeof Tag.map | typeof Tag.sorted;
+    }
+    /** Match Type from Tag symbol */
+    type TypeFromTag<Kind extends Tag.T> = Kind extends typeof Tag.bool ? Bool : Kind extends typeof Tag.bytes ? Uint8Array : Kind extends typeof Tag.timestamp ? Timestamp : Kind extends typeof Tag.float ? Float : Kind extends typeof Tag.int32 ? Int32 : Kind extends typeof Tag.int64 ? Int64 : Kind extends typeof Tag.nil ? Null : Kind extends typeof Tag.text ? Text : Kind extends typeof Tag.coordinates ? Coordinates : Kind extends typeof Tag.map ? Map : Kind extends typeof Tag.sorted ? Sorted<any> : never;
+}
+/** Field */
+export type FieldValueType<T = any> = FT.Any<T>;
+/** Document */
+export type DocumentType<F extends FieldValueType = any> = {
+    [fieldId: string]: F;
+};
+/** Collection */
+export type CollectionType = {
+    [documentId: string]: DocumentType;
+};
+/** Database */
+export type DatabaseType = {
+    [collectionId: string]: CollectionType;
+};
+/** Cluster */
+export type ClusterType = {
+    [databaseId: string]: DatabaseType;
+};
+/**
+ * Outlines schemas for entity types (e.g., field, doc, collection)
+ */
+export declare namespace Schema {
+    /**
+     * Name fields
+     */
+    type Name = {
+        singular?: FT.Text;
+        plural?: FT.Text;
+    };
+    /**
+     * Interface properties for a timestamp lifecycle
+     *
+     * @export
+     * @interface StampedLifecycle
+     */
+    type StampedLifecycle = Partial<Record<StampedKeys, FT.Timestamp>>;
+    type StampedKeys = 'created' | 'updated' | 'delete';
+    /** Just a boxed name field */
+    interface NamedField {
+        name: Name;
+    }
+    /**
+     * Describes the meta object for a field instance
+     */
+    interface FieldDefinition extends NamedField {
+        type: FT.Tag.T;
+        description?: FT.Text;
+    }
+    /**
+     * Outlines the fields to be designated for a new
+     * document instance within the parent collection
+     */
+    type ModelFields = {
+        [fieldId: string]: FieldDefinition;
+    };
+    /**
+     * Describes a collection of documents, the fields
+     * property describes the fields of any document an
+     * instance of the collection.
+     */
+    interface CollectionModel extends DocumentType, StampedLifecycle, NamedField {
+        fields: ModelFields;
+    }
+    /**
+     * Describes a collection of documents, each document
+     * only describes another collection e.g. the meta
+     */
+    type CollectionModels = CollectionType & {
+        [collectionIdAsDocumentId: string]: CollectionModel;
+    };
+    /**
+     * =======================================================
+     */
+    /**
+     * The actual collection instance of a collection meta
+     */
+    type CollectionInstance<T extends CollectionModel> = CollectionType & {
+        [documentId: string]: DocumentType<FT.TypeFromTag<T['fields'][string]['type']>>;
+    };
+    /**
+     * Just simply a database of collections
+     */
+    type DatabaseCollections<C extends CollectionModels> = DatabaseType & {
+        [CID in keyof C]: CollectionInstance<C[CID]>;
+    };
+}
+export declare namespace Ref {
+    interface Base<S = any> {
+        id: PKey;
+        schema: S;
+    }
+    /**
+     * =======================================================
+     */
+    type Field<S extends Schema.FieldDefinition> = FT.TypeFromTag<S['type']>;
+    /**
+     * =======================================================
+     */
+    type DocumentFields<S extends Schema.ModelFields> = {
+        [K in keyof S]: Field<S[K]>;
+    };
+    type Document<S extends Schema.ModelFields> = DocumentFields<S>;
+    /**
+     * =======================================================
+     */
+    type CollectionDocuments<S extends Schema.CollectionModel> = {
+        [documentId: string]: Document<S['fields']>;
+    };
+    type Collection<S extends Schema.CollectionModel> = CollectionDocuments<S>;
+    /**
+     * =======================================================
+     */
+    interface Database {
+        schemas: Schema.CollectionModels;
+        instances: Schema.DatabaseCollections<this['schemas']>;
+    }
+}
+/**
+ * Evaluation kinds
+ */
+export declare enum Eval {
+    Required = "r6d",
+    Regex = "r3x"
+}
+/**
+ * Property name index signatures
+ */
+export declare const Sig: {
+    Field: string;
+    Fields: string;
+    Document: string;
+    Documents: string;
+    Collection: string;
+    Collections: string;
+    Subcollection: string;
+    Subcollections: string;
+    Model: string;
+    Models: string;
+    Blueprint: string;
+    Blueprints: string;
+    Entry: string;
+    Entries: string;
+    Id: string;
+    Name: string;
+    Kind: string;
+    Type: string;
+    Value: string;
+    Created: string;
+    Updated: string;
+    Deleted: string;
+};
+/**
+ * Friendly-text/display-names of local names or
+ *
+ * TODO: i18n
+ */
+export declare const lbl: {
+    /** Entity type fields */
+    [Sig.Field]: string;
+    [Sig.Fields]: string;
+    [Sig.Document]: string;
+    [Sig.Documents]: string;
+    [Sig.Collection]: string;
+    [Sig.Collections]: string;
+    [Sig.Subcollection]: string;
+    [Sig.Subcollections]: string;
+    /** Instance fields */
+    [Sig.Blueprint]: string;
+    [Sig.Blueprints]: string;
+    [Sig.Model]: string;
+    [Sig.Models]: string;
+    [Sig.Entry]: string;
+    [Sig.Entries]: string;
+    /** Meta fields */
+    [Sig.Id]: string;
+    [Sig.Name]: string;
+    [Sig.Kind]: string;
+    [Sig.Type]: string;
+    [Sig.Value]: string;
+    /** Timestamp fields */
+    [Sig.Created]: string;
+    [Sig.Updated]: string;
+    [Sig.Deleted]: string;
+    /** Field Data Types */
+    bool: string;
+    bytes: string;
+    timestamp: string;
+    float: string;
+    int32: string;
+    int64: string;
+    nil: string;
+    text: string;
+    coordinates: string;
+    map: string;
+    sorted: string;
+};
+/** Contextual persistence types */
+export declare enum Persistance {
+    NONE = "NONE",
+    SESSION = "SESSION",
+    LOCAL = "LOCAL"
+}
+export {};

package/src/lib/dod.js

@@ -0,0 +1,150 @@
+/**
+ * @license
+ * Copyright 2023 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /*
+ * NOTE (AGL-177): this file is the 2023-era type-level design doc. The
+ * RUNTIME source of truth for dataset models now lives in
+ * `libs/aglyn/src/lib/app-utils/dataset-models.ts` — extend that module,
+ * not this one.
+ */ /**
+ * (D)Document-(o)oriented (D)Database (DoD)
+ *
+ * A document-oriented database, or DoD, or document
+ * store, is a data storage structure designed for
+ * storing, retrieving and managing document-oriented
+ * information, also known as semi-structured data.
+ *
+ * Each document contains a set of key-value pairs.
+ * All documents must be stored in collections.
+ *
+ * Documents can contain literal fields such as
+ * text/strings, numbers, or booleans, and secondly
+ * nestable fields such as arrays or mapped objects.
+ *
+ * The special sauce here which deviates from a
+ * traditional DoD is the overlaid design patterns
+ * which provide the outlines for capabilities such
+ * as relational- and model-driven
+ *
+ * @module dod
+ */ /** Primary key */ (function(FT) {
+    (function(Tag) {
+        Tag.bool = 'bool';
+        Tag.bytes = 'bytes';
+        Tag.timestamp = 'timestamp';
+        Tag.float = 'float';
+        Tag.int32 = 'int32';
+        Tag.int64 = 'int64';
+        Tag.nil = 'nil';
+        Tag.text = 'text';
+        Tag.coordinates = 'coordinates';
+        Tag.map = 'map';
+        Tag.sorted = 'sorted';
+        Tag.all = [
+            FT.Tag.bool,
+            FT.Tag.bytes,
+            FT.Tag.timestamp,
+            FT.Tag.float,
+            FT.Tag.int32,
+            FT.Tag.int64,
+            FT.Tag.nil,
+            FT.Tag.text,
+            FT.Tag.coordinates,
+            FT.Tag.map,
+            FT.Tag.sorted
+        ];
+    })(FT.Tag || (FT.Tag = {}));
+})(FT || (FT = {}));
+/**
+ * Evaluation kinds
+ */ export var Eval = /*#__PURE__*/ function(Eval) {
+    Eval["Required"] = "r6d";
+    Eval["Regex"] = "r3x";
+    return Eval;
+}({});
+/**
+ * Property name index signatures
+ */ export const Sig = {
+    Field: 'field',
+    Fields: 'fields',
+    Document: 'document',
+    Documents: 'documents',
+    Collection: 'collection',
+    Collections: 'collections',
+    Subcollection: 'subcollection',
+    Subcollections: 'subcollections',
+    Model: 'model',
+    Models: 'models',
+    Blueprint: 'blueprint',
+    Blueprints: 'blueprints',
+    Entry: 'entry',
+    Entries: 'entries',
+    Id: 'id',
+    Name: 'name',
+    Kind: 'kind',
+    Type: 'type',
+    Value: 'value',
+    Created: 'created',
+    Updated: 'updated',
+    Deleted: 'deleted'
+};
+/**
+ * Friendly-text/display-names of local names or
+ *
+ * TODO: i18n
+ */ export const lbl = {
+    /** Field Data Types */ [FT.Tag.bool]: 'True/False',
+    [FT.Tag.bytes]: 'Bytes',
+    [FT.Tag.timestamp]: 'Date/Time',
+    [FT.Tag.float]: 'Decimal',
+    [FT.Tag.int32]: 'Number',
+    [FT.Tag.int64]: 'Large Number',
+    [FT.Tag.nil]: 'Null',
+    [FT.Tag.text]: 'Text',
+    [FT.Tag.coordinates]: 'Coordinates (lat/lon)',
+    [FT.Tag.map]: 'Map',
+    [FT.Tag.sorted]: 'Sorted',
+    /** Entity type fields */ [Sig.Field]: 'Field',
+    [Sig.Fields]: 'Fields',
+    [Sig.Document]: 'Document',
+    [Sig.Documents]: 'Documents',
+    [Sig.Collection]: 'Collection',
+    [Sig.Collections]: 'Collections',
+    [Sig.Subcollection]: 'Subcollection',
+    [Sig.Subcollections]: 'Subcollections',
+    /** Instance fields */ [Sig.Blueprint]: 'Blueprint',
+    [Sig.Blueprints]: 'Blueprints',
+    [Sig.Model]: 'Model',
+    [Sig.Models]: 'Models',
+    [Sig.Entry]: 'Entry',
+    [Sig.Entries]: 'Entries',
+    /** Meta fields */ [Sig.Id]: 'Unique ID',
+    [Sig.Name]: 'Display Name',
+    [Sig.Kind]: 'Kind',
+    [Sig.Type]: 'Type',
+    [Sig.Value]: 'Value',
+    /** Timestamp fields */ [Sig.Created]: 'Created At',
+    [Sig.Updated]: 'Updated At',
+    [Sig.Deleted]: 'Deleted At'
+};
+/** Contextual persistence types */ export var Persistance = /*#__PURE__*/ function(Persistance) {
+    Persistance["NONE"] = "NONE";
+    Persistance["SESSION"] = "SESSION";
+    Persistance["LOCAL"] = "LOCAL";
+    return Persistance;
+}({});
+export var FT;
+
+//# sourceMappingURL=dod.js.map

package/src/lib/dod.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/data/types/src/lib/dod.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2023 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/*\n * NOTE (AGL-177): this file is the 2023-era type-level design doc. The\n * RUNTIME source of truth for dataset models now lives in\n * `libs/aglyn/src/lib/app-utils/dataset-models.ts` — extend that module,\n * not this one.\n */\n\n/**\n * (D)Document-(o)oriented (D)Database (DoD)\n *\n * A document-oriented database, or DoD, or document\n * store, is a data storage structure designed for\n * storing, retrieving and managing document-oriented\n * information, also known as semi-structured data.\n *\n * Each document contains a set of key-value pairs.\n * All documents must be stored in collections.\n *\n * Documents can contain literal fields such as\n * text/strings, numbers, or booleans, and secondly\n * nestable fields such as arrays or mapped objects.\n *\n * The special sauce here which deviates from a\n * traditional DoD is the overlaid design patterns\n * which provide the outlines for capabilities such\n * as relational- and model-driven\n *\n * @module dod\n */\n\n/** Primary key */\nexport type PKey = string\n/** Foreign key */\nexport type FKey = string\n/** Alternate key */\nexport type AKey = string\n\n/** Tuple with exactly two nodes */\nexport interface TupleLn2<T1, T2 = T1> extends Array<T1 | T2> {\n  0: T1\n  1: T2\n  length: 2 // using the numeric literal type '2'\n}\n\n/** Tuple with a minimum of one nodes */\ninterface TupleMinLn1<T> extends Array<T> {\n  0: T\n}\n\n/** Tuple with a minimum of two nodes */\ninterface TupleMinLn2<T1, T2 = T1> extends TupleMinLn1<T1 | T2> {\n  0: T1\n  1: T2\n}\n\n/**\n * Nominal Type hack to declare a typeof type for\n * a unique symbol. This is because `unique symbol`\n * can only be typed from a const.\n *\n * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-7.html#unique-symbol\n */\ndeclare const NominalSymbol: unique symbol\nexport type UniqSym = typeof NominalSymbol\n\n/**\n * Describes relationship design patterns to\n * outline a RDBMS equivalent\n */\nexport namespace Relation {\n  /**\n   * A associative lookup for unnatural/extrinsic\n   * Many-to-Many relationship.\n   *\n   * Note: intrinsic 2-way relations should live within\n   * both documents and not use an extra query/join for\n   * the lookup! However, a rare scenario that it is too\n   * large, you may store the most recent (n) items in\n   * the two documents and use the lookup for the rest.\n   *\n   * Consider the following 2-way relationship:\n   * group1 = [user1, user3]\n   * group2 = [user1, user2]\n   * group3 = [user2, user3]\n   * user1 = [group1, group2]\n   * user2 = [group2, group3]\n   * user3 = [group1, group3]\n   *\n   * That would be displayed in an associative as follows:\n   * AK1 = [group1, user1]\n   * AK2 = [group1, user3]\n   * AK3 = [group2, user1]\n   * AK4 = [group2, user2]\n   * AK5 = [group3, user2]\n   * AK6 = [group3, user3]\n   */\n  export type Associative = TupleLn2<FKey>\n\n  /**\n   * Similar to an associative relation but rather to\n   * find many associations\n   *\n   * e.g. Invoice, Product, User lookups\n   * AK1 = [invoiceId, productId, userId]\n   */\n  export type Lookup = TupleMinLn2<FKey>\n}\n\n/** Field Type */\nexport namespace FT {\n  export type Bool = boolean\n  export type Bytes = Uint8Array | string\n  export type Timestamp = number\n  export type Float = number\n  export type Int32 = number\n  export type Int64 = number\n  export type Null = null\n  export type Text = string\n  export type Coordinates = Record<'longitude' | 'latitude', number>\n  export type Map = Dictionary\n  export type Sorted<T = any> = T extends any[] ? never : T[]\n\n  export type Nestable = Map | Sorted<any>\n\n  export type Any<T = any> =\n    | Sorted<T>\n    | Bool\n    | Bytes\n    | Timestamp\n    | Float\n    | Coordinates\n    | Int32\n    | Int64\n    | Map\n    | Null\n    | Text\n\n  export namespace Tag {\n    export const bool = 'bool'\n    export const bytes = 'bytes'\n    export const timestamp = 'timestamp'\n    export const float = 'float'\n    export const int32 = 'int32'\n    export const int64 = 'int64'\n    export const nil = 'nil'\n    export const text = 'text'\n    export const coordinates = 'coordinates'\n    export const map = 'map'\n    export const sorted = 'sorted'\n\n    export const all = [\n      Tag.bool,\n      Tag.bytes,\n      Tag.timestamp,\n      Tag.float,\n      Tag.int32,\n      Tag.int64,\n      Tag.nil,\n      Tag.text,\n      Tag.coordinates,\n      Tag.map,\n      Tag.sorted,\n    ]\n\n    export type T =\n      | typeof Tag.bool\n      | typeof Tag.bytes\n      | typeof Tag.timestamp\n      | typeof Tag.float\n      | typeof Tag.int32\n      | typeof Tag.int64\n      | typeof Tag.nil\n      | typeof Tag.text\n      | typeof Tag.coordinates\n      | typeof Tag.map\n      | typeof Tag.sorted\n  }\n\n  /** Match Type from Tag symbol */\n  export type TypeFromTag<Kind extends Tag.T> = Kind extends typeof Tag.bool\n    ? Bool\n    : Kind extends typeof Tag.bytes\n      ? Uint8Array\n      : Kind extends typeof Tag.timestamp\n        ? Timestamp\n        : Kind extends typeof Tag.float\n          ? Float\n          : Kind extends typeof Tag.int32\n            ? Int32\n            : Kind extends typeof Tag.int64\n              ? Int64\n              : Kind extends typeof Tag.nil\n                ? Null\n                : Kind extends typeof Tag.text\n                  ? Text\n                  : Kind extends typeof Tag.coordinates\n                    ? Coordinates\n                    : Kind extends typeof Tag.map\n                      ? Map\n                      : Kind extends typeof Tag.sorted\n                        ? Sorted<any>\n                        : never\n}\n\n/** Field */\nexport type FieldValueType<T = any> = FT.Any<T>\n/** Document */\nexport type DocumentType<F extends FieldValueType = any> = {\n  [fieldId: string]: F\n}\n/** Collection */\nexport type CollectionType = {[documentId: string]: DocumentType}\n/** Database */\nexport type DatabaseType = {[collectionId: string]: CollectionType}\n/** Cluster */\nexport type ClusterType = {[databaseId: string]: DatabaseType}\n\n/**\n * Outlines schemas for entity types (e.g., field, doc, collection)\n */\nexport namespace Schema {\n  /**\n   * Name fields\n   */\n  export type Name = {\n    singular?: FT.Text\n    plural?: FT.Text\n  }\n\n  /**\n   * Interface properties for a timestamp lifecycle\n   *\n   * @export\n   * @interface StampedLifecycle\n   */\n  export type StampedLifecycle = Partial<Record<StampedKeys, FT.Timestamp>>\n  export type StampedKeys = 'created' | 'updated' | 'delete'\n\n  /** Just a boxed name field */\n  export interface NamedField {\n    name: Name\n  }\n\n  /**\n   * Describes the meta object for a field instance\n   */\n  export interface FieldDefinition extends NamedField {\n    type: FT.Tag.T\n    description?: FT.Text\n  }\n\n  /**\n   * Outlines the fields to be designated for a new\n   * document instance within the parent collection\n   */\n  export type ModelFields = {\n    [fieldId: string]: FieldDefinition\n  }\n\n  /**\n   * Describes a collection of documents, the fields\n   * property describes the fields of any document an\n   * instance of the collection.\n   */\n  export interface CollectionModel\n    extends DocumentType,\n      StampedLifecycle,\n      NamedField {\n    fields: ModelFields\n  }\n\n  /**\n   * Describes a collection of documents, each document\n   * only describes another collection e.g. the meta\n   */\n  export type CollectionModels = CollectionType & {\n    [collectionIdAsDocumentId: string]: CollectionModel\n  }\n\n  /**\n   * =======================================================\n   */\n\n  /**\n   * The actual collection instance of a collection meta\n   */\n  export type CollectionInstance<T extends CollectionModel> = CollectionType & {\n    [documentId: string]: DocumentType<\n      FT.TypeFromTag<T['fields'][string]['type']>\n    >\n  }\n\n  /**\n   * Just simply a database of collections\n   */\n  export type DatabaseCollections<C extends CollectionModels> = DatabaseType & {\n    [CID in keyof C]: CollectionInstance<C[CID]>\n  }\n}\n\nexport namespace Ref {\n  export interface Base<S = any> {\n    id: PKey\n    schema: S\n  }\n\n  /**\n   * =======================================================\n   */\n  export type Field<S extends Schema.FieldDefinition> = FT.TypeFromTag<\n    S['type']\n  >\n\n  /**\n   * =======================================================\n   */\n  export type DocumentFields<S extends Schema.ModelFields> = {\n    [K in keyof S]: Field<S[K]>\n  }\n  export type Document<S extends Schema.ModelFields> = DocumentFields<S>\n\n  /**\n   * =======================================================\n   */\n  export type CollectionDocuments<S extends Schema.CollectionModel> = {\n    [documentId: string]: Document<S['fields']>\n  }\n  export type Collection<S extends Schema.CollectionModel> =\n    CollectionDocuments<S>\n\n  /**\n   * =======================================================\n   */\n    // export type DatabaseCollections<S extends Schema.CollectionModels> = {\n    //   [K in keyof S]: Collection<S[K]>\n    // }\n  export interface Database {\n    schemas: Schema.CollectionModels\n    instances: Schema.DatabaseCollections<this['schemas']>\n  }\n}\n\n/**\n * Evaluation kinds\n */\nexport enum Eval {\n  Required = 'r6d',\n  Regex = 'r3x',\n}\n\n/**\n * Property name index signatures\n */\nexport const Sig = {\n  Field: 'field',\n  Fields: 'fields',\n  Document: 'document',\n  Documents: 'documents',\n  Collection: 'collection',\n  Collections: 'collections',\n  Subcollection: 'subcollection',\n  Subcollections: 'subcollections',\n\n  Model: 'model',\n  Models: 'models',\n  Blueprint: 'blueprint',\n  Blueprints: 'blueprints',\n  Entry: 'entry',\n  Entries: 'entries',\n\n  Id: 'id',\n  Name: 'name',\n  Kind: 'kind',\n  Type: 'type',\n  Value: 'value',\n\n  Created: 'created',\n  Updated: 'updated',\n  Deleted: 'deleted',\n}\n\n/**\n * Friendly-text/display-names of local names or\n *\n * TODO: i18n\n */\nexport const lbl = {\n  /** Field Data Types */\n  [FT.Tag.bool]: 'True/False',\n  [FT.Tag.bytes]: 'Bytes',\n  [FT.Tag.timestamp]: 'Date/Time',\n  [FT.Tag.float]: 'Decimal',\n  [FT.Tag.int32]: 'Number',\n  [FT.Tag.int64]: 'Large Number',\n  [FT.Tag.nil]: 'Null',\n  [FT.Tag.text]: 'Text',\n  [FT.Tag.coordinates]: 'Coordinates (lat/lon)',\n  [FT.Tag.map]: 'Map',\n  [FT.Tag.sorted]: 'Sorted',\n\n  /** Entity type fields */\n  [Sig.Field]: 'Field',\n  [Sig.Fields]: 'Fields',\n  [Sig.Document]: 'Document',\n  [Sig.Documents]: 'Documents',\n  [Sig.Collection]: 'Collection',\n  [Sig.Collections]: 'Collections',\n  [Sig.Subcollection]: 'Subcollection',\n  [Sig.Subcollections]: 'Subcollections',\n\n  /** Instance fields */\n  [Sig.Blueprint]: 'Blueprint',\n  [Sig.Blueprints]: 'Blueprints',\n  [Sig.Model]: 'Model',\n  [Sig.Models]: 'Models',\n  [Sig.Entry]: 'Entry',\n  [Sig.Entries]: 'Entries',\n\n  /** Meta fields */\n  [Sig.Id]: 'Unique ID',\n  [Sig.Name]: 'Display Name',\n  [Sig.Kind]: 'Kind',\n  [Sig.Type]: 'Type',\n  [Sig.Value]: 'Value',\n\n  /** Timestamp fields */\n  [Sig.Created]: 'Created At',\n  [Sig.Updated]: 'Updated At',\n  [Sig.Deleted]: 'Deleted At',\n}\n\n/** Contextual persistence types */\nexport enum Persistance {\n  NONE = 'NONE',\n  SESSION = 'SESSION',\n  LOCAL = 'LOCAL',\n}\n"],"names":["FT","Tag","bool","bytes","timestamp","float","int32","int64","nil","text","coordinates","map","sorted","all","Eval","Sig","Field","Fields","Document","Documents","Collection","Collections","Subcollection","Subcollections","Model","Models","Blueprint","Blueprints","Entry","Entries","Id","Name","Kind","Type","Value","Created","Updated","Deleted","lbl","Persistance"],"mappings":"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"}

package/src/lib/host-theme.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Persisted host theme document types.
+ *
+ * These are plain-JSON (Firestore round-trippable) descriptions of a MUI
+ * theme. They intentionally carry no MUI imports so data-scope libs can
+ * depend on them; `@aglyn/shared-ui-theme` owns the conversion into runtime
+ * `ThemeOptions`.
+ */
+export type HostThemeScheme = 'light' | 'dark';
+export interface HostThemePaletteColor {
+    main: string;
+    light?: string;
+    dark?: string;
+    contrastText?: string;
+}
+/**
+ * Pale washes of the three accents, used as SURFACES (AGL-1244).
+ *
+ * Deliberately NOT a {@link HostThemePaletteColor}: a tint has no ramp and no
+ * `contrastText`, because it is never a component `color`. It is the fill
+ * behind an icon that is already `primary.dark` / `secondary.main` /
+ * `tertiary.main`, so its members are named after the accent they belong to
+ * rather than after a shade. Same shape as `background` and `text` — a group
+ * of string leaves — which is why the theme editor reads and writes it
+ * through the same path-based fields.
+ */
+export interface HostThemeTintColors {
+    primary?: string;
+    secondary?: string;
+    tertiary?: string;
+}
+/** Palette color keys supported per scheme, including repo-custom ones. */
+export interface HostThemeSchemeColors {
+    primary?: HostThemePaletteColor;
+    secondary?: HostThemePaletteColor;
+    tertiary?: HostThemePaletteColor;
+    surface?: HostThemePaletteColor;
+    error?: HostThemePaletteColor;
+    warning?: HostThemePaletteColor;
+    info?: HostThemePaletteColor;
+    success?: HostThemePaletteColor;
+    background?: {
+        default?: string;
+        paper?: string;
+    };
+    text?: {
+        primary?: string;
+        secondary?: string;
+        disabled?: string;
+    };
+    tint?: HostThemeTintColors;
+    divider?: string;
+}
+export interface HostThemeFont {
+    /** Font family name, e.g. "Inter". */
+    family: string;
+    weights?: Array<number>;
+    /** Where the tenant loads the font from; system fonts need no loading. */
+    source?: 'google' | 'system';
+}
+export type HostThemeTypographyVariantKey = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'subtitle1' | 'subtitle2' | 'body1' | 'body2' | 'button' | 'caption' | 'overline';
+export interface HostThemeTypographyVariant {
+    fontFamily?: string;
+    fontSize?: string | number;
+    fontWeight?: number;
+    lineHeight?: string | number;
+    letterSpacing?: string | number;
+    textTransform?: 'none' | 'capitalize' | 'uppercase' | 'lowercase';
+}
+export interface HostThemeTypography {
+    /** CSS font-family stack applied theme-wide. */
+    fontFamily?: string;
+    variants?: {
+        [P in HostThemeTypographyVariantKey]?: HostThemeTypographyVariant;
+    };
+}
+/**
+ * Plain-JSON component override: serialized `defaultProps` and
+ * `styleOverrides` (slot name -> CSS object). Functions are not
+ * representable by design.
+ */
+export interface HostThemeComponentOverride {
+    defaultProps?: Record<string, unknown>;
+    styleOverrides?: Record<string, unknown>;
+}
+/**
+ * Plain-JSON theme mixins.
+ *
+ * `toolbar` is the only one a host can set, and it exists because it is the
+ * ONLY way to change toolbar height from data (AGL-1242). MUI builds the
+ * Toolbar's `regular` variant style FROM `theme.mixins.toolbar`, and applies
+ * that variant AFTER `components.MuiToolbar.styleOverrides` — so a slot
+ * override can never win, no matter how it is written. The value is a CSS
+ * object and may nest media queries, e.g.
+ * `{ minHeight: '56px', '@media (min-width:600px)': { minHeight: '72px' } }`.
+ */
+export interface HostThemeMixins {
+    toolbar?: Record<string, unknown>;
+}
+export interface HostTheme {
+    colorSchemes?: {
+        [P in HostThemeScheme]?: HostThemeSchemeColors;
+    };
+    typography?: HostThemeTypography;
+    fonts?: Array<HostThemeFont>;
+    shape?: {
+        borderRadius?: number;
+    };
+    spacing?: number;
+    mixins?: HostThemeMixins;
+    /** Keyed by MUI component slot name (e.g. `MuiButton`). Consumers validate against a whitelist. */
+    components?: Record<string, HostThemeComponentOverride>;
+    /**
+     * Whether visitors get a dark scheme. Absent (`'auto'`) follows the
+     * visitor's system setting or their choice in the theme mode switcher,
+     * rendering the platform's default dark palette under whatever dark colors
+     * the site authored. `'off'` keeps every visitor on light — for a site whose
+     * content carries light-only backgrounds — and hides the switcher on
+     * published pages.
+     */
+    darkScheme?: 'auto' | 'off';
+}

package/src/lib/host-theme.js

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Persisted host theme document types.
+ *
+ * These are plain-JSON (Firestore round-trippable) descriptions of a MUI
+ * theme. They intentionally carry no MUI imports so data-scope libs can
+ * depend on them; `@aglyn/shared-ui-theme` owns the conversion into runtime
+ * `ThemeOptions`.
+ */ export { };
+
+//# sourceMappingURL=host-theme.js.map