diff --git a/packages/ts/models/src/builders.ts b/packages/ts/models/src/builders.ts index 4879a6a5fd..c734228979 100644 --- a/packages/ts/models/src/builders.ts +++ b/packages/ts/models/src/builders.ts @@ -14,6 +14,9 @@ import { const { create, defineProperty } = Object; +/** + * The options for creating the model property. + */ export type ModelBuilderPropertyOptions = Readonly<{ meta?: ModelMetadata; }>; @@ -49,12 +52,6 @@ export type Flags = { * @typeParam EX - The extra properties of the model. * @typeParam F - The flags for the model constructor that allow to determine * specific characteristics of the model. - * - * @param base - The base model to extend. - * @param defaultValueProvider - The function that provides the default value - * for the model. - * - * @internal */ export class CoreModelBuilder< V, @@ -63,6 +60,11 @@ export class CoreModelBuilder< > { protected readonly [$model]: Model; + /** + * @param base - The base model to extend. + * @param defaultValueProvider - The function that provides the default value + * for the model. + */ constructor(base: Model, defaultValueProvider?: (model: Model) => V) { this[$model] = create(base); @@ -163,9 +165,6 @@ const propertyRegistry = new WeakMap>(); * @typeParam EX - The extra properties of the model. * @typeParam F - The flags for the model constructor that allow to determine * specific characteristics of the model. - * - * - * @internal */ export class ObjectModelBuilder< V extends AnyObject, diff --git a/packages/ts/models/src/core.ts b/packages/ts/models/src/core.ts index 69f0540c10..289a227844 100644 --- a/packages/ts/models/src/core.ts +++ b/packages/ts/models/src/core.ts @@ -2,18 +2,33 @@ import type { EmptyObject } from 'type-fest'; import { CoreModelBuilder } from './builders.js'; import { $enum, $itemModel, type $members, type AnyObject, type Enum, Model, type Value } from './model.js'; +/** + * The model of a primitive value, like `string`, `number` or `boolean`. + */ export type PrimitiveModel = Model; export const PrimitiveModel = new CoreModelBuilder(Model, (): unknown => undefined).name('primitive').build(); +/** + * The model of a string value. + */ export type StringModel = PrimitiveModel; export const StringModel = new CoreModelBuilder(PrimitiveModel, () => '').name('string').build(); +/** + * The model of a number value. + */ export type NumberModel = PrimitiveModel; export const NumberModel = new CoreModelBuilder(PrimitiveModel, () => 0).name('number').build(); +/** + * The model of a boolean value. + */ export type BooleanModel = PrimitiveModel; export const BooleanModel = new CoreModelBuilder(PrimitiveModel, () => false).name('boolean').build(); +/** + * The model of an array data. + */ export type ArrayModel = Model< Array>, Readonly<{ @@ -26,10 +41,16 @@ export const ArrayModel = new CoreModelBuilder(Model, (): unknown[] => []) .define($itemModel, { value: Model }) .build(); +/** + * The model of an object data. + */ export type ObjectModel = Model; export const ObjectModel = new CoreModelBuilder(Model, (): AnyObject => ({})).name('Object').build(); +/** + * The model of an enum data. + */ export type EnumModel = Model< T[keyof T], Readonly<{ @@ -44,4 +65,7 @@ export const EnumModel = new CoreModelBuilder<(typeof Enum)[keyof typeof Enum]>( .defaultValueProvider((self) => Object.values(self[$enum])[0]) .build(); +/** + * The model of a union data. + */ export type UnionModel = Model, Readonly<{ [$members]: MM }>>; diff --git a/packages/ts/models/src/index.ts b/packages/ts/models/src/index.ts index caf03445c4..bd137cec73 100644 --- a/packages/ts/models/src/index.ts +++ b/packages/ts/models/src/index.ts @@ -22,6 +22,7 @@ import { export * from './model.js'; export * from './core.js'; +export type * from './builders.js'; const { defineProperty } = Object; @@ -41,7 +42,18 @@ function getRawValue(model: Model): T | typeof nothing { return (model[$owner] as Target).value; } +/** + * The utility object that provides methods to create and manipulate models. + */ const m = { + /** + * Attaches the given model to the target. + * + * @param model - The model to attach. + * @param target - The target to attach the model to. It could be a Binder + * instance, a Signal, or another object. However, it could never be another + * model. + */ attach(model: M, target: Target>): M { const _model = new CoreModelBuilder, Extensions, { named: false; selfRefKeys: References }>(model) .name(`@${model[$name]}`) diff --git a/packages/ts/models/src/model.ts b/packages/ts/models/src/model.ts index b30093bd46..a2d83f5b6e 100644 --- a/packages/ts/models/src/model.ts +++ b/packages/ts/models/src/model.ts @@ -45,19 +45,67 @@ export declare enum Enum {} export type AnyObject = Readonly>; // {} +/* eslint-disable tsdoc/syntax */ +/** + * The symbol that represents the {@link Model[$key]} property. + */ export const $key = Symbol('key'); + +/** + * The symbol that represents the {@link Model[$name]} property. + */ export const $name = Symbol('name'); + +/** + * The symbol that represents the {@link Model[$owner]} property. + */ export const $owner = Symbol('owner'); + +/** + * The symbol that represents the {@link Model[$meta]} property. + */ export const $meta = Symbol('meta'); + +/** + * The symbol that represents the {@link Model[$optional]} property. + */ export const $optional = Symbol('optional'); + +/** + * The symbol that represents the {@link Model[$value]} property. + */ export const $defaultValue = Symbol('value'); -export const $enum = Symbol('enum'); +/** + * The symbol that represents the {@link EnumModel[$enumerate]} property. + */ +export const $enum = Symbol('enumerate'); + +/** + * The symbol that represents the {@link UnionModel[$members]} property. + */ export const $members = Symbol('members'); + +/** + * The symbol that represents the {@link ArrayModel[$itemModel]} property. + */ export const $itemModel = Symbol('itemModel'); +/* eslint-enable tsdoc/syntax */ + +/** + * Extracts the value type the model represents. + */ export type Value = M extends Model ? T : never; + +/** + * Extracts the list of extra properties of the model. + */ export type Extensions = M extends Model ? EX : EmptyObject; + +/** + * Extracts the list of self-referencing properties of the model. + */ export type References = M extends Model ? R : never; /**