@furo/open-models 0.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 open-models
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,27 @@
+## Naming Conventions
+The generated models are using camelCase notation for the field names, the UseProtoNames uses whatever was defined in the contract.
+If a name start with an underscore, the model will use an X for the first letter.
+
+`_user` => `XUser`
+
+https://github.com/googleapis/googleapis/blob/master/google/api/field_behavior.proto
+
+## Validators
+
+### Class Validators
+
+### Instance Validators
+
+## Options
+```js
+import {OPEN_MODELS_OPTIONS} from "./x/@furo/open-models/core/OPEN_MODELS_OPTIONS";
+
+OPEN_MODELS_OPTIONS.labelFormatter = (l)=> customTranslator(l.replaceAll('.','_').toUpperCase())
+```
+
+
+## CustomPrototypes
+
+## Reserved words
+- toString
+- valueOf

package/dist/CustomPrototypes.d.ts

@@ -0,0 +1,6 @@
+type str = (d: any) => string;
+type nr = (d: any) => number;
+type typeName = string;
+export declare const ToString: Map<typeName, str>;
+export declare const ValueOf: Map<typeName, nr>;
+export {};

package/dist/CustomPrototypes.js

@@ -0,0 +1,4 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const ToString = new Map();
+export const ValueOf = new Map();
+//# sourceMappingURL=CustomPrototypes.js.map

package/dist/CustomPrototypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CustomPrototypes.js","sourceRoot":"","sources":["../src/CustomPrototypes.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAU9D,MAAM,CAAC,MAAM,QAAQ,GAAuB,IAAI,GAAG,EAAiB,CAAC;AACrE,MAAM,CAAC,MAAM,OAAO,GAAsB,IAAI,GAAG,EAAgB,CAAC","sourcesContent":["// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype str = (d: any) => string;\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype nr = (d: any) => number;\n\n// Full qualified type name\ntype typeName = string;\n\nexport const ToString: Map<typeName, str> = new Map<typeName, str>();\nexport const ValueOf: Map<typeName, nr> = new Map<typeName, nr>();\n"]}

package/dist/FDM_OPTIONS.d.ts

@@ -0,0 +1,16 @@
+export interface Options {
+    UseProtoNames: boolean;
+    /**
+     * Replace with your own label formatter, if you want to use translations for the labels.
+     * @param key
+     */
+    labelFormatter: (key: string) => string;
+    EmitUnpopulated: boolean;
+    EmitDefaultValues: boolean;
+    /**
+     * Use this method to translate the value state messages.
+     * @param key
+     */
+    valueStateMessageFormatter: (key: string[]) => string;
+}
+export declare const FDM_OPTIONS: Options;

package/dist/FDM_OPTIONS.js

@@ -0,0 +1,8 @@
+export const FDM_OPTIONS = {
+    UseProtoNames: true,
+    labelFormatter: key => key.replaceAll('.', '_').toUpperCase(),
+    EmitDefaultValues: false,
+    EmitUnpopulated: false,
+    valueStateMessageFormatter: key => key.join(' '),
+};
+//# sourceMappingURL=FDM_OPTIONS.js.map

package/dist/FDM_OPTIONS.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FDM_OPTIONS.js","sourceRoot":"","sources":["../src/FDM_OPTIONS.ts"],"names":[],"mappings":"AAuDA,MAAM,CAAC,MAAM,WAAW,GAAY;IAClC,aAAa,EAAE,IAAI;IACnB,cAAc,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE;IAC7D,iBAAiB,EAAE,KAAK;IACxB,eAAe,EAAE,KAAK;IACtB,0BAA0B,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC;CACjD,CAAC","sourcesContent":["export interface Options {\n\n  // UseProtoNames uses proto field name instead of lowerCamelCase name in JSON\n  // field names.\n  // UseProtoNames bool\n  UseProtoNames: boolean;\n  /**\n   * Replace with your own label formatter, if you want to use translations for the labels.\n   * @param key\n   */\n  labelFormatter: (key: string) => string;\n\n  // EmitUnpopulated specifies whether to emit unpopulated fields. It does not\n  // emit unpopulated oneof fields or unpopulated extension fields.\n  // The JSON value emitted for unpopulated fields are as follows:\n  //  ╔═══════╤════════════════════════════╗\n  //  ║ JSON  │ Protobuf field             ║\n  //  ╠═══════╪════════════════════════════╣\n  //  ║ false │ proto3 boolean fields      ║\n  //  ║ 0     │ proto3 numeric fields      ║\n  //  ║ \"\"    │ proto3 string/bytes fields ║\n  //  ║ null  │ proto2 scalar fields       ║\n  //  ║ null  │ message fields             ║\n  //  ║ []    │ list fields                ║\n  //  ║ {}    │ map fields                 ║\n  //  ╚═══════╧════════════════════════════╝\n  EmitUnpopulated: boolean;\n\n  // EmitDefaultValues specifies whether to emit default-valued primitive fields,\n  // empty lists, and empty maps. The fields affected are as follows:\n  //  ╔═══════╤════════════════════════════════════════╗\n  //  ║ JSON  │ Protobuf field                         ║\n  //  ╠═══════╪════════════════════════════════════════╣\n  //  ║ false │ non-optional scalar boolean fields     ║\n  //  ║ 0     │ non-optional scalar numeric fields     ║\n  //  ║ \"\"    │ non-optional scalar string/byte fields ║\n  //  ║ []    │ empty repeated fields                  ║\n  //  ║ {}    │ empty map fields                       ║\n  //  ╚═══════╧════════════════════════════════════════╝\n  //\n  // Behaves similarly to EmitUnpopulated, but does not emit \"null\"-value fields,\n  // i.e. presence-sensing fields that are omitted will remain omitted to preserve\n  // presence-sensing.\n  // EmitUnpopulated takes precedence over EmitDefaultValues since the former generates\n  // a strict superset of the latter.\n  // EmitDefaultValues: boolean;\n\n  EmitDefaultValues: boolean;\n  /**\n   * Use this method to translate the value state messages.\n   * @param key\n   */\n  valueStateMessageFormatter: (key: string[]) => string;\n}\n\nexport const FDM_OPTIONS: Options = {\n  UseProtoNames: true,\n  labelFormatter: key => key.replaceAll('.', '_').toUpperCase(),\n  EmitDefaultValues: false,\n  EmitUnpopulated: false,\n  valueStateMessageFormatter: key => key.join(' '),\n};\n"]}

package/dist/FieldConstraints.d.ts

@@ -0,0 +1,15 @@
+export interface FieldConstraints {
+    multiple_of?: number | undefined;
+    maximum?: number | undefined;
+    minimum?: number | undefined;
+    exclusive_maximum?: boolean | undefined;
+    exclusive_minimum?: boolean | undefined;
+    max_length?: number | undefined;
+    min_length?: number | undefined;
+    pattern?: string | undefined;
+    max_items?: number | undefined;
+    min_items?: number | undefined;
+    unique_items?: boolean | undefined;
+    not?: FieldConstraints | undefined;
+    required?: boolean | undefined;
+}

package/dist/FieldConstraints.js

@@ -0,0 +1,3 @@
+// The constraints are quite similar to https://swagger.io/docs/specification/data-models/data-types/
+export {};
+//# sourceMappingURL=FieldConstraints.js.map

package/dist/FieldConstraints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldConstraints.js","sourceRoot":"","sources":["../src/FieldConstraints.ts"],"names":[],"mappings":"AAAA,qGAAqG","sourcesContent":["// The constraints are quite similar to https://swagger.io/docs/specification/data-models/data-types/\n\nexport interface FieldConstraints {\n  // NUMERIC CONSTRAINTS\n  // Use the multipleOf keyword to specify that a number must be the multiple of another number\n  multiple_of?: number | undefined;\n  // Use the minimum and maximum keywords to specify the range of possible values. \"<=\" is used to check.\n  maximum?: number | undefined;\n  // Use the minimum and maximum keywords to specify the range of possible values. \">=\" is used to check.\n  minimum?: number | undefined;\n  // makes maximum using < instead of <=\n  exclusive_maximum?: boolean | undefined;\n  // makes minimum using < instead of >=\n  exclusive_minimum?: boolean | undefined;\n\n  // STRING CONSTRAINTS\n  // String length can be restricted using minLength and maxLength. \"<\" is used to check.\n  max_length?: number | undefined;\n  // String length can be restricted using minLength and maxLength. \">\" is used to check.\n  min_length?: number | undefined;\n  // The pattern keyword lets you define a regular expression template for the string value.\n  pattern?: string | undefined;\n\n  // ARRAY CONSTRAINTS\n  // Array size can be restricted using min_items and max_items.  \"<=\" is used to check.\n  max_items?: number | undefined;\n  // Array size can be restricted using min_items and max_items.  \">=\" is used to check.\n  min_items?: number | undefined;\n  // You can use uniqueItems: true to specify that all items in the array must be unique. ?? Set ??\n  unique_items?: boolean | undefined;\n\n  // use this to negate\n  not?: FieldConstraints | undefined; // {not:{max_items:4,min_items:4}} or not:{multiple_of:7}\n\n  required?: boolean | undefined;\n}\n"]}

package/dist/FieldNode.d.ts

@@ -0,0 +1,339 @@
+/**
+ * notes: i18n is not part of the api anymore
+ */
+import { ValueState } from './ValueState.js';
+import { FieldConstraints } from './FieldConstraints.js';
+type EventType = 'field-value-changed' | 'this-field-value-changed' | 'this-state-changed' | 'state-changed' | 'validity-changed' | 'array-changed' | 'this-array-changed' | 'map-changed' | 'this-map-changed' | 'model-injected';
+type Meta = {
+    index?: number;
+    oldValue?: unknown;
+    initialValue: unknown;
+    typeName: string;
+    fieldName?: string;
+    valueState: ValueState;
+    stateMessage: string;
+    nodeFields: FieldDescriptor[];
+    readonly: boolean;
+    required: boolean;
+    isArrayNode: boolean;
+    isRecursionNode: boolean;
+    isAnyNode: boolean;
+    isValid: boolean;
+    isPristine: boolean;
+    eventListener: Map<string, {
+        callbackfn: CustomEventListener;
+        options?: AddEventListenerOptions | boolean;
+    }[]>;
+};
+/**
+ * Primitives have always a value field
+ */
+interface IPrimitive extends FieldNode {
+    _value: unknown;
+}
+interface CustomEventListener {
+    (evt: CustomEvent): void;
+}
+type FieldDescriptor = {
+    fieldName: string;
+    jsonName: string;
+    FieldConstructor: any;
+    ValueConstructor?: new () => FieldNode;
+    constraints?: FieldConstraints;
+};
+export interface ValueStateSummary {
+    /**
+     * path of the field
+     *
+     * `fullName` for a violation in the `fullName` value
+     * `emailAddresses[1].email` for a violation in the `email` field of the first `emailAddresses` message
+     * `emailAddresses[3].type[2]` for a violation in the second `type` value in the third `emailAddresses` message.
+     */
+    field: string;
+    state: ValueState;
+    message: string;
+}
+export declare abstract class FieldNode {
+    protected ___isEmpty: boolean;
+    /**
+     * Marker for primitive types
+     */
+    __isPrimitive: boolean;
+    /**
+     * Parent node of a node. This is undefined on root nodes.
+     */
+    __parentNode: FieldNode | undefined;
+    /**
+     * Meta data of a field node.
+     */
+    __meta: Meta;
+    private ___rootNode;
+    private ___readonlyState;
+    /**
+     * Root node of a node
+     */
+    get __rootNode(): FieldNode;
+    /**
+     * Root node of a node. Do not set this value by yourself.
+     * @param value
+     */
+    set __rootNode(value: FieldNode);
+    /**
+     * Empty state of the node
+     */
+    get __isEmpty(): boolean;
+    /**
+     * Empty state of the node
+     * @param empty
+     */
+    set __isEmpty(empty: boolean);
+    constructor(_initData: undefined, parent?: FieldNode, parentAttributeName?: string);
+    /**
+     * Get a FieldNode by giving a field path using the proto names for the fields.
+     *
+     *
+     *
+     * - `email_addresses[3].type[2]` for the second `type` value in the third `email_addresses` message.
+     * - `user.location.street` for the street in location in user.
+     *
+     * @param {string} deepPath - Path of the field.
+     */
+    __getFieldNodeByPath(deepPath?: string): FieldNode | undefined;
+    set __readonly(v: boolean);
+    get __readonly(): boolean;
+    /**
+     * Build up the model with the literal type. The literal type matches the interface from ITypeName.
+     * @param {} literal - The literal type matches the interface from ITypeName.
+     */
+    __fromLiteral(literal: unknown): void;
+    private __setModelValidStateTrue;
+    /**
+     * Updates the model from literal data, without changing the validity and value state.
+     *
+     * @param literal
+     */
+    __updateWithLiteral(literal: unknown): void;
+    __stringify(): string;
+    /**
+     * Converts the model to a JSON struct wich matches the protobuf spec.
+     * If the `UseProtoNames` option is set to false, lowerCamelCase is produced.
+     */
+    __toJson(): any;
+    /**
+     * Build up the model, using the transport Json. If UseProtoNames is set to false, lowerCamelCase is expected.
+     *
+     * @param {JSON} data - Transport Json
+     */
+    __fromJson(data: any): void;
+    /**
+     * Helper function to create a literal type from a json type
+     * @param {JSON} data - Transport Json
+     */
+    __mapJsonToLiteral(data: any): any;
+    /**
+     * Converts the model to a literal type. The literal type matches the interface from ITypeName.
+     */
+    __toLiteral(): any;
+    get __fieldPath(): string;
+    ___pathBuilder(parts: string[]): string[];
+    get __label(): string;
+    get __placeholder(): string;
+    get __ariaDescription(): string;
+    /**
+     * Returns a list of all states of a node and its children.
+     *
+     * ```json
+     * [
+     *   {
+     *      "field": "id",
+     *      "state": "Error",
+     *      "message": "This field is invalid"
+     *   },
+     *     {
+     *      "field": "display_name",
+     *      "state": "Error",
+     *      "message": "This field is invalid"
+     *   }
+     * ]
+     * ```
+     */
+    __getAllStates(): ValueStateSummary[];
+    private ___getAllStates;
+    /**
+     * Applies a list of  states to a node and its children.
+     *
+     * Keep in mind, that the message must be already translated.
+     *
+     * ```json
+     * {
+     *    "field": "id",
+     *    "state": "Error",
+     *    "message": "This field is invalid"
+     *}
+     *
+     * ```
+     *
+     */
+    __applyValueStates(...states: ValueStateSummary[]): void;
+    /**
+     * Returns the valid state of a node.
+     * - A node is valid when all children are valid.
+     * - A node is valid when freshly initialized, even when some children have invalid values.
+     *
+     * use `validate()` to be sure to have the correct validity state.
+     *
+     * Use __meta.StateMessage to receive the state of a node. The `__meta.StateMessage` is only available on an explicit field, where the validity state is populated upwards.
+     */
+    get __isValid(): boolean;
+    /**
+     * Initialized fields are pristine as long nothing changes inside the model.
+     *
+     * Use this on rootNodes only.
+     */
+    get __isPristine(): boolean;
+    /**
+     * The toString() method of Object instances returns a string representing this object. This method is meant to be overridden by `CustomPrototypes.ToString`.
+     * If no `CustomPrototypes` is set, it will try to find a display_name attribute on the node and uses that for the output.
+     *
+     * If there is no display_name `[object TypeName]` is returned.
+     */
+    toString(): string;
+    /**
+     * The valueOf() method of Object instances converts the this value to an object.
+     * This method is meant to be overridden by derived objects for custom type conversion logic.
+     */
+    valueOf(): number;
+    /**
+     * Helper method to build up labels, placeholders,...
+     * @protected
+     */
+    protected __getBaseName(): string;
+    /**
+     * Helper method to construct the __fieldPath
+     * @param parts
+     * @protected
+     */
+    protected ___fieldNameBuilder(parts: string[]): string[];
+    /**
+     * Validate the node and all child nodes of it.
+     */
+    __validate(): void;
+    /**
+     * Validates all parents of an element. This is done when you set a value on any child/attribute of a node directly
+     * @param {FieldNode} node - Any FieldNode
+     */
+    protected __validateBottomUp(node: FieldNode): void;
+    /**
+     * Validates all parent nodes if a sub-field was changed.
+     * @protected
+     */
+    protected __climbUpValidation(): void;
+    /**
+     * Additional "constraint" checker for primitive types, i.e. INT32 can only range from -2147483648 to 2147483647, but js uses always a float64 to handle numbers
+     * @protected
+     */
+    protected __checkTypeBoundaries(): string[] | undefined;
+    /**
+     * Executes the validation process.
+     * @param node
+     * @protected
+     */
+    protected __validationExecuter(node: FieldNode): void;
+    /**
+     * Receives all constraints of a node. Use this in your custom validators or components.
+     */
+    __getConstraints(): FieldConstraints | undefined;
+    /**
+     * Set the value state
+     * @param {ValueState} state - The state of the node.
+     * @param {string[]} message - Description for the formatter.
+     */
+    __setValueState(state: ValueState, message: string[]): void;
+    /**
+     * Resets the node to the last inserted literal or to the initial state.
+     * // todo: reset to default values not just the empty state
+     */
+    __reset(): void;
+    /**
+     * Clear clears the element downwards and set __isEmpty to true on all sub nodes.
+     *
+     * A cleared field is not populated on `__toLiteral` or `__toJson` when the option `EmitUnpopulated` or `EmitDefaultValues` is set to false.
+     */
+    __clear(): void;
+    /**
+     * Helper method to update a skalar / primitive field of a type. Used by the generated models.
+     * Triggers also the validation and clearance, if needed.
+     *
+     * @param {FieldNode} targetNode - The field of a FieldNode
+     * @param {string | boolean | number} value - The value you want to set
+     * @protected
+     */
+    protected __PrimitivesSetter(targetNode: IPrimitive, value: unknown): void;
+    /**
+     * Helper method to update a field of a type. Used by the generated models.
+     * Triggers also the validation and clearance, if needed.
+     *
+     * @param {FieldNode} targetNode - The field of a FieldNode
+     * @param {} literalData - The literal type matches the interface from ITypeName.
+     * @protected
+     */
+    protected __TypeSetter(targetNode: FieldNode, literalData: unknown | undefined | null): void;
+    /**
+     * Notifies field changes
+     * @param bubbles
+     * @protected
+     */
+    protected __notifyFieldValueChange(bubbles?: boolean): void;
+    /**
+     * Returns the child nodes of a node.
+     */
+    get __childNodes(): any[];
+    /**
+     * Broadcast an event to all child nodes of a field node.
+     * @param event
+     */
+    __broadcastEvent(event: CustomEvent): void;
+    /**
+     * Dispatches a custom event on a FieldNode
+     * @param {CustomEvent} event - A generic custom event.
+     */
+    __dispatchEvent(event: CustomEvent): CustomEvent;
+    /**
+     * Helper method to invoke/execute the event on the current node
+     * @param event
+     * @protected
+     */
+    protected __triggerNodeEvents(event: CustomEvent<FieldNode>): void;
+    /**
+     * Add a handler to a node
+     * @param {string} type - A case-sensitive string representing the event type to listen for.
+     * @param {function} listener - The object that receives a notification (an object that implements the Event interface) when an event of the specified type occurs. This must be null, an object with a handleEvent() method, or a JavaScript function. See The event listener callback for details on the callback itself.
+     * @param {} options - An object that specifies characteristics about the event listener. \n\nThe available option is `once:boolean`
+     */
+    __addEventListener(type: EventType, listener: CustomEventListener, options?: boolean | AddEventListenerOptions): void;
+    __addCustomEventListener(type: string, handler: CustomEventListener, options?: boolean | AddEventListenerOptions): void;
+    /**
+     * Removes the handler from a node
+     * @param type
+     * @param handler
+     * @param options
+     */
+    __removeEventListener(type: EventType, handler: CustomEventListener, options?: boolean | EventListenerOptions): void;
+    /**
+     * Removes the handler from a node
+     * @param type
+     * @param handler
+     * @param options
+     */
+    __removeCustomEventListener(type: string, handler: CustomEventListener, options?: boolean | EventListenerOptions): void;
+    /**
+     * if some child is not empty, set isEmpty to false, all the way up to the root node
+     * @private
+     */
+    protected ___updateNotEmptyPath(): void;
+    protected __checkConstraints(fieldConstraints: FieldConstraints): string[] | undefined;
+    private __toLowerCamelCase;
+    private __toLowerCamelCaseWithoutXPrefix;
+    private __toSnakeCase;
+}
+export {};