@xmobitea/gn-typescript-client 2.6.13 → 2.6.14

package/dist/runtime/entity/DataMember.d.ts

@@ -1,77 +1,415 @@
 import "reflect-metadata";
 import { GNArray, GNHashtable } from "./../common/GNData";
 import { AbstractConstructor, Constructor, GNObjectFieldMetadata, GNObjectMetadata } from "./GNMetadata";
+/**
+ * Lazily allocates the metadata blob for a class prototype, walking up
+ * the prototype chain so subclasses inherit a deep-cloned `fields`
+ * array from their parent class.
+ *
+ * Why the cloning: the reflection blob is mutable — every
+ * `@*DataMember` decorator pushes a new entry into `fields` or
+ * mutates an existing one. Without per-class cloning, decorating a
+ * subclass field would alter the parent's metadata too, which would
+ * break the (de)serialiser for any sibling subclass that depends on
+ * the unmodified parent layout.
+ *
+ * Recursion termination: when the prototype is `Object.prototype` the
+ * helper returns an empty placeholder. The first concrete prototype
+ * that does not yet own `__GN_METADATA__` then seeds its own blob by
+ * spreading the inherited one (`...superPrototype`) and shallow-cloning
+ * each field entry.
+ *
+ * @param prototype  Class prototype to ensure metadata exists on.
+ * @returns The metadata blob attached to (or freshly allocated for)
+ *          `prototype`.
+ *
+ * @template T Concrete metadata interface (typically
+ *             {@link GNEnhancedObjectMetadata}).
+ */
 export declare const initGNObjectMetadata: <T extends GNObjectMetadata>(prototype: any) => T;
+/**
+ * Lazily allocates the per-field metadata entry for `propertyKey` on
+ * `prototype`.
+ *
+ * Behaviour:
+ * - If the property is decorated for the first time the helper reads
+ *   the TypeScript reflection data via
+ *   {@link getGNReflectedMetadata}, builds a fresh
+ *   {@link GNObjectFieldMetadata} entry and pushes it into the parent
+ *   metadata's `fields` array.
+ * - If the property already has an entry (typical when multiple
+ *   decorators are stacked on the same field) the existing entry is
+ *   shallow-cloned so the caller can mutate the clone without
+ *   affecting any inherited copy that might still be referenced by
+ *   sibling subclasses.
+ *
+ * @param prototype    Class prototype that owns the property.
+ * @param propertyKey  Decorated property name.
+ * @returns The mutable field metadata entry that the decorator should
+ *          continue populating with `code`, `isOptional`,
+ *          `defaultValue`, etc.
+ *
+ * @template T Concrete enhanced field metadata
+ *             ({@link GNEnhancedObjectFieldMetadata}).
+ */
 export declare const initGNObjectFieldMetadata: <T extends GNObjectFieldMetadata>(prototype: any, propertyKey: string) => T;
+/**
+ * Reads the GearN reflection blob attached to `obj`'s prototype.
+ *
+ * Returns `undefined` when the class has no decorated members yet, so
+ * callers must null-check the result before iterating
+ * `metadata.fields`.
+ *
+ * @param obj Class reference (concrete or abstract). Only the
+ *            prototype is inspected — the function does not invoke
+ *            `new`.
+ *
+ * @template T Expected metadata shape — usually
+ *             {@link GNEnhancedObjectMetadata}.
+ */
 export declare const getGNObjectMetadata: <T extends GNObjectMetadata>(obj: AbstractConstructor<any>) => T | undefined;
+/**
+ * Replaces the GearN reflection blob attached to `obj`'s prototype.
+ *
+ * Intended for advanced testing scenarios where a synthesised metadata
+ * blob is injected onto a class. Production code should rely on the
+ * `@*DataMember` decorators to manage the blob automatically.
+ *
+ * @param obj      Class reference whose prototype receives the blob.
+ * @param metadata Replacement metadata.
+ */
 export declare const setGNObjectMetadata: <T extends GNObjectMetadata>(obj: AbstractConstructor<any>, metadata: T) => void;
+/**
+ * Builds the default `id` value stored on a model's
+ * {@link GNObjectMetadata}.
+ *
+ * Currently the lower-cased constructor name. Used solely for
+ * diagnostic output — the (de)serialiser never reads the id.
+ *
+ * @returns The lower-cased class name, or `undefined` when `model` is
+ *          itself nullish.
+ */
 export declare const getTableName: (model: Constructor<any>) => string;
+/**
+ * Field metadata enriched with the SDK-specific serialisation hints
+ * supplied by the `@*DataMember` decorator family.
+ *
+ * Stored on the model prototype inside the `fields` array of
+ * {@link GNEnhancedObjectMetadata}. The serializer in
+ * {@link ConverterService} reads each field at runtime to map a
+ * model property onto the corresponding wire-level
+ * {@link ParameterCode} key.
+ */
 export interface GNEnhancedObjectFieldMetadata extends GNObjectFieldMetadata {
+    /**
+     * Wire-level parameter key used when (de)serialising the field —
+     * typically a constant from {@link ParameterCode}.
+     */
     code: string;
+    /**
+     * When `true`, a `null` value is allowed and is omitted from the
+     * outbound payload entirely. When `false`, a `null` value is
+     * still serialised (sent as JSON `null` / MsgPack nil) so the
+     * backend can distinguish "explicit clear" from "untouched".
+     */
     isOptional: boolean;
+    /** Coarse value bucket used by the serializer's branching logic. */
     gnFieldType: GNFieldDataType;
+    /**
+     * Value substituted in during deserialisation when the wire
+     * payload omits the field.
+     */
     defaultValue: any;
+    /**
+     * Set to `true` by the decorator when at least one validation
+     * constraint (`mustNonNull`, `min*`, `max*`, `mustInt`) was
+     * supplied. Reserved for the upcoming client-side validation
+     * step — the runtime reads it but no enforcement code currently
+     * fires on it.
+     */
     activeConditionValid: boolean;
+    /** String/Hashtable/Array constraint: forbid `null` values. */
     mustNonNull?: boolean;
+    /**
+     * String/Hashtable/Array constraint: minimum allowed length
+     * (characters / keys / elements).
+     */
     minLength?: number;
+    /** String/Hashtable/Array constraint: maximum allowed length. */
     maxLength?: number;
+    /** Number constraint: minimum allowed value (inclusive). */
     minValue?: number;
+    /** Number constraint: maximum allowed value (inclusive). */
     maxValue?: number;
+    /** Number constraint: reject non-integer values. */
     mustInt?: boolean;
 }
+/**
+ * Coarse runtime type bucket used by the GearN serializer.
+ *
+ * `Other` is the catch-all for fields decorated with the bare
+ * `@DataMember` decorator (no specific shape declared). Numeric
+ * ordinals are an internal detail and are never persisted to the
+ * wire.
+ */
 export declare enum GNFieldDataType {
+    /** Generic `@DataMember` — any value, no type-specific handling. */
     Other = 0,
+    /** `@NumberDataMember` — numeric primitive. */
     Number = 1,
+    /** `@StringDataMember` — string primitive. */
     String = 2,
+    /** `@BooleanDataMember` — boolean primitive. */
     Boolean = 3,
+    /** `@GNHashtableDataMember` — nested object. */
     GNHashtable = 4,
+    /** `@GNArrayDataMember` — nested list. */
     GNArray = 5
 }
+/**
+ * Class-level metadata for a decorated GearN model.
+ *
+ * Specialises {@link GNObjectMetadata} so that the `fields` array
+ * uses the enhanced per-field shape that the (de)serialiser actually
+ * consumes.
+ */
 export interface GNEnhancedObjectMetadata extends GNObjectMetadata {
+    /** Ordered list of decorated fields. */
     fields: GNEnhancedObjectFieldMetadata[];
 }
+/**
+ * Common base shape shared by every `@*DataMember` decorator.
+ */
 interface DataMemberBaseArgs {
+    /**
+     * Wire-level parameter key, normally a constant from
+     * {@link ParameterCode}. Required because the serializer uses it
+     * as the dictionary key on the outbound `GNHashtable`.
+     */
     code: string;
+    /**
+     * Mark the field as optional so that a `null` value is dropped
+     * from the outbound payload instead of being serialised as JSON
+     * `null` / MsgPack nil. Defaults to `false`.
+     */
     isOptional?: boolean;
+    /**
+     * Value injected into the model during deserialisation when the
+     * wire payload omits the field.
+     */
     defaultValue?: any;
 }
+/**
+ * Argument shape for the generic {@link DataMember} decorator.
+ */
 interface DataMemberArgs extends DataMemberBaseArgs {
+    /**
+     * Optional override for the coarse value bucket. Most callers
+     * leave this `undefined` so the decorator falls back to
+     * {@link GNFieldDataType.Other}; specialised decorators
+     * (`StringDataMember`, etc.) set it explicitly.
+     */
     gnFieldType?: GNFieldDataType;
 }
+/**
+ * Convenience alias used by the type-specific decorator argument
+ * shapes below — purely organisational, no extra fields.
+ */
 interface OtherDataMemberArgs extends DataMemberBaseArgs {
 }
+/**
+ * Argument shape for {@link StringDataMember}.
+ */
 interface StringDataMemberArgs extends OtherDataMemberArgs {
+    /** Default value injected when the field is missing on the wire. */
     defaultValue?: string;
+    /** Reject `null` values. Activates client-side validation. */
     mustNonNull?: boolean;
+    /** Minimum string length, inclusive. Defaults to `0` when unset. */
     minLength?: number;
+    /**
+     * Maximum string length, inclusive. Defaults to `256` when
+     * unset and any constraint is supplied.
+     */
     maxLength?: number;
 }
+/**
+ * Argument shape for {@link BooleanDataMember}.
+ */
 interface BooleanDataMemberArgs extends OtherDataMemberArgs {
+    /** Default boolean value injected when the field is missing. */
     defaultValue?: boolean;
 }
+/**
+ * Argument shape for {@link NumberDataMember}.
+ */
 interface NumberDataMemberArgs extends OtherDataMemberArgs {
+    /** Default numeric value injected when the field is missing. */
     defaultValue?: number;
+    /**
+     * Minimum numeric value, inclusive. Defaults to `-Infinity`
+     * when any constraint is supplied.
+     */
     minValue?: number;
+    /**
+     * Maximum numeric value, inclusive. Defaults to `Infinity` when
+     * any constraint is supplied.
+     */
     maxValue?: number;
+    /** Reject fractional values. Activates client-side validation. */
     mustInt?: boolean;
 }
+/**
+ * Argument shape for {@link GNHashtableDataMember}.
+ */
 interface GNHashtableDataMemberArgs extends OtherDataMemberArgs {
+    /** Default {@link GNHashtable} substituted when missing. */
     defaultValue?: GNHashtable;
+    /** Reject `null` values. Activates client-side validation. */
     mustNonNull?: boolean;
+    /** Minimum number of keys, inclusive. Defaults to `0` when unset. */
     minLength?: number;
+    /** Maximum number of keys, inclusive. Defaults to `256` when unset. */
     maxLength?: number;
 }
+/**
+ * Argument shape for {@link GNArrayDataMember}.
+ */
 interface GNArrayDataMemberArgs extends OtherDataMemberArgs {
+    /** Default {@link GNArray} substituted when missing. */
     defaultValue?: GNArray;
+    /** Reject `null` values. Activates client-side validation. */
     mustNonNull?: boolean;
+    /** Minimum number of elements, inclusive. */
     minLength?: number;
+    /** Maximum number of elements, inclusive. */
     maxLength?: number;
+    /**
+     * Concrete element class. Required when the array contains typed
+     * model instances so the (de)serialiser knows which class to
+     * instantiate per element. For arrays of primitives pass the
+     * matching wrapper (`String`, `Number`, `Boolean`).
+     */
     elementCls?: new (...args: any[]) => any;
 }
+/**
+ * Generic property decorator used for fields without a
+ * type-specific shape.
+ *
+ * Falls back to {@link GNFieldDataType.Other} when the caller does
+ * not pin `gnFieldType`. Validation cannot be activated through this
+ * decorator — use the type-specific variants for that.
+ *
+ * @example
+ * ```ts
+ * class Item {
+ *     @DataMember({ code: ParameterCode.Value })
+ *     public value: any;
+ * }
+ * ```
+ *
+ * @param args Decorator arguments — see {@link DataMemberArgs}.
+ */
 export declare const DataMember: (args: DataMemberArgs) => (prototype: any, propertyKey: string) => void;
+/**
+ * Property decorator for `string` fields.
+ *
+ * Activates client-side validation when at least one of `mustNonNull`,
+ * `minLength` or `maxLength` is supplied. The activation also fills
+ * in default values for the missing constraints (`mustNonNull = false`,
+ * `minLength = 0`, `maxLength = 256`) so that the validation step has
+ * a complete profile to work against.
+ *
+ * @example
+ * ```ts
+ * class Login {
+ *     @StringDataMember({ code: ParameterCode.Username, minLength: 6, maxLength: 32, mustNonNull: true })
+ *     public username: string;
+ * }
+ * ```
+ *
+ * @param args Decorator arguments — see {@link StringDataMemberArgs}.
+ */
 export declare const StringDataMember: (args: StringDataMemberArgs) => (prototype: any, propertyKey: string) => void;
+/**
+ * Property decorator for `boolean` fields.
+ *
+ * Validation cannot be activated for booleans — the only knobs are
+ * `code`, `isOptional` and `defaultValue`.
+ *
+ * @example
+ * ```ts
+ * class Param {
+ *     @BooleanDataMember({ code: ParameterCode.External, isOptional: true, defaultValue: false })
+ *     public external?: boolean;
+ * }
+ * ```
+ *
+ * @param args Decorator arguments — see {@link BooleanDataMemberArgs}.
+ */
 export declare const BooleanDataMember: (args: BooleanDataMemberArgs) => (prototype: any, propertyKey: string) => void;
+/**
+ * Property decorator for nested {@link GNHashtable}-shaped fields
+ * (object instances).
+ *
+ * Activates client-side validation when at least one of
+ * `mustNonNull`, `minLength` or `maxLength` is supplied. Default
+ * activation values mirror those of {@link StringDataMember}
+ * (`mustNonNull = false`, `minLength = 0`, `maxLength = 256`).
+ *
+ * @example
+ * ```ts
+ * class Login {
+ *     @GNHashtableDataMember({ code: ParameterCode.InfoRequestParam, mustNonNull: true })
+ *     public infoRequestParam: InfoRequestParam;
+ * }
+ * ```
+ *
+ * @param args Decorator arguments — see {@link GNHashtableDataMemberArgs}.
+ */
 export declare const GNHashtableDataMember: (args: GNHashtableDataMemberArgs) => (prototype: any, propertyKey: string) => void;
+/**
+ * Property decorator for nested {@link GNArray}-shaped fields
+ * (lists / arrays).
+ *
+ * The `elementCls` argument is recorded as the field's `cls` so the
+ * (de)serialiser knows which constructor to instantiate per element.
+ * For arrays of primitives pass the matching wrapper (`String`,
+ * `Number`, `Boolean`).
+ *
+ * Activates client-side validation when at least one of
+ * `mustNonNull`, `minLength` or `maxLength` is supplied, with the
+ * same default-fill behaviour as {@link StringDataMember}.
+ *
+ * @example
+ * ```ts
+ * class Param {
+ *     @GNArrayDataMember({ code: ParameterCode.PlayerDataKeys, isOptional: true, elementCls: String })
+ *     public playerDataKeys?: Array<string>;
+ * }
+ * ```
+ *
+ * @param args Decorator arguments — see {@link GNArrayDataMemberArgs}.
+ */
 export declare const GNArrayDataMember: (args: GNArrayDataMemberArgs) => (prototype: any, propertyKey: string) => void;
+/**
+ * Property decorator for `number` fields.
+ *
+ * Activates client-side validation when at least one of `mustInt`,
+ * `minValue` or `maxValue` is supplied. Default activation values
+ * widen the bounds to `[-Infinity, +Infinity]` and disable the
+ * integer constraint so the validation step never rejects a value
+ * the caller did not explicitly opt in to.
+ *
+ * @example
+ * ```ts
+ * class Param {
+ *     @NumberDataMember({ code: ParameterCode.Type, minValue: 1, maxValue: 2, mustInt: true })
+ *     public type: number;
+ * }
+ * ```
+ *
+ * @param args Decorator arguments — see {@link NumberDataMemberArgs}.
+ */
 export declare const NumberDataMember: (args: NumberDataMemberArgs) => (prototype: any, propertyKey: string) => void;
 export {};

package/dist/runtime/entity/GNMetadata.d.ts

@@ -1,22 +1,123 @@
+/**
+ * Type alias for an instantiable class — anything that supports `new
+ * SomeClass(...args)` and produces a `T`.
+ *
+ * The SDK uses this alias as the "deserialise into" parameter for
+ * helpers like {@link ConverterService.deserializeObject},
+ * {@link ConverterService.deserializeArray} and the typed `sendVia*`
+ * helpers on {@link GNNetwork}. Passing a class through this type
+ * preserves enough static information that TypeScript can infer the
+ * generic `T` automatically:
+ *
+ * ```ts
+ * function decode<T>(value: any, cls: Constructor<T>): T {
+ *     return new cls(value);
+ * }
+ * const ban = decode(rawValue, GenericModels.BanItem); // T = BanItem
+ * ```
+ *
+ * @template T  Instance type produced by the constructor.
+ */
 export type Constructor<T> = {
     new (...args: any[]): T;
 };
+/**
+ * Type alias for a possibly-abstract class reference.
+ *
+ * Used wherever the SDK only needs to read static or prototype-level
+ * metadata (decorator-attached `__GN_METADATA__` blob, prototype field
+ * definitions) without ever calling `new`. Abstract classes have no
+ * `new(...)` signature, so the standard {@link Constructor} alias would
+ * reject them — `AbstractConstructor` widens the constraint to plain
+ * `Function & { prototype: T }`.
+ *
+ * Mainly used by {@link getGNObjectMetadata} and
+ * {@link setGNObjectMetadata} so callers can hand in either a concrete
+ * model class or an abstract base class.
+ *
+ * @template T  Instance type that the prototype represents.
+ */
 export type AbstractConstructor<T> = Function & {
     prototype: T;
 };
+/**
+ * Coarse runtime type of a model field as observed by `Reflect.getMetadata`.
+ *
+ * The `DataMember` decorator family inspects the TypeScript-emitted
+ * `design:type` metadata to learn which JavaScript constructor was
+ * declared on a field (`String`, `Number`, `Boolean`, `Array`, anything
+ * else). Those constructors are then mapped onto this enum so the
+ * serializer / deserializer in {@link ConverterService} can branch on
+ * the kind of value they're handling without re-inspecting the class.
+ *
+ * The numeric ordinals are an internal contract — they are never
+ * persisted to the wire — but should still not be reordered casually
+ * because every cached metadata blob references them by value.
+ */
 export declare enum FieldDataType {
+    /** Field is declared as `boolean` / `Boolean`. */
     Boolean = 0,
+    /** Field is declared as `number` / `Number`. */
     Number = 1,
+    /** Field is declared as `string` / `String`. */
     String = 2,
+    /** Field is declared as `Array<...>` (or `T[]`). */
     Array = 3,
+    /** Field is declared as a class instance — anything that is not one of the primitives above. */
     Object = 4
 }
+/**
+ * Per-field reflected metadata captured by the `DataMember` decorator
+ * family.
+ *
+ * Stored in the `__GN_METADATA__` blob attached to the model prototype.
+ * The base contract here only covers the values the runtime needs to
+ * navigate the prototype chain; the `DataMember` decorators extend it
+ * with serialisation-specific fields by widening to
+ * {@link GNEnhancedObjectFieldMetadata}.
+ */
 export interface GNObjectFieldMetadata {
+    /**
+     * Property key on the model prototype (e.g. `"username"` or
+     * `"infoRequestParam"`). Used by the (de)serialiser to read /
+     * write values via `obj[name]`.
+     */
     name: string;
+    /**
+     * Coarse type bucket inferred from the TypeScript `design:type`
+     * metadata. See {@link FieldDataType} for the enum members.
+     */
     fieldType: FieldDataType;
+    /**
+     * Concrete element / value class declared on the field. For
+     * primitives this is the corresponding wrapper constructor
+     * (`String`, `Number`, `Boolean`); for object fields it is the
+     * declared class; for arrays it is the element class supplied via
+     * `GNArrayDataMember({ elementCls })`.
+     */
     cls: new (...args: any[]) => any;
 }
+/**
+ * Per-class reflected metadata captured by the `DataMember` decorator
+ * family.
+ *
+ * Each model prototype owns its own metadata blob; subclasses inherit a
+ * cloned copy of the parent's `fields` array so they can add or
+ * override entries without mutating the base class. The `id` field is
+ * the lower-cased class name and is currently informational — the
+ * serialiser never reads it.
+ */
 export interface GNObjectMetadata {
+    /**
+     * Lowercase class name. Filled by {@link initGNObjectMetadata}
+     * using `model.name.toLowerCase()` and used for diagnostic
+     * purposes only — the serializer does not read it.
+     */
     id: string;
+    /**
+     * Ordered list of decorated field metadata entries. The order
+     * matches the declaration order of the `@*DataMember` decorators
+     * on the class plus any inherited entries from parent classes.
+     */
     fields: GNObjectFieldMetadata[];
 }

package/dist/runtime/entity/InvalidMember.d.ts

@@ -1,5 +1,33 @@
 import { InvalidMemberType } from "./../constant/enumType/InvalidMemberType";
+/**
+ * Single entry in the `invalidRequestParameters` list returned by
+ * the backend when validation rejects a request.
+ *
+ * The SDK only ships this value through
+ * {@link OperationResponse.getInvalidMembers}, populated by
+ * {@link PeerBase.onResponseHandler} when the response carries the
+ * `invalidRequestParameters` array. Each entry tells the
+ * application **which** parameter failed and **why**, so the
+ * caller can surface a precise validation error in the UI.
+ *
+ * Wire layout: each entry is sent as a two-element array
+ * `[code, invalidMemberType]` — the SDK unpacks it into this
+ * struct shape for ergonomics.
+ */
 export interface InvalidMember {
+    /**
+     * Wire-level parameter key that failed validation. Matches the
+     * `code` value declared by the corresponding
+     * `@*DataMember({ code: ParameterCode.X })` decorator on the
+     * request model, so the application can map the failure back
+     * to a specific input field.
+     */
     code: string;
+    /**
+     * Discriminator describing why the parameter was rejected
+     * (missing, out of range, wrong type, ...). Decoded by
+     * {@link CodeHelper.getInvalidMemberName} when the SDK needs a
+     * human-readable label.
+     */
     invalidMemberType: InvalidMemberType;
 }

package/dist/runtime/entity/OperationEvent.d.ts

@@ -1,11 +1,60 @@
 import { GNHashtable } from "./../common/GNData";
+/**
+ * Low-level container for a server-pushed event delivered over the
+ * socket transport.
+ *
+ * The SDK builds one of these in {@link SocketPeer.onEventHandler}
+ * for every decoded event frame, then dispatches it to:
+ * - the single-slot raw observer registered through
+ *   {@link GNNetwork.setOnEventHandler}; and
+ * - every typed {@link IServerEventHandler} whose `getEventCode()`
+ *   matches the event's code.
+ *
+ * Events are different from responses in two ways: they carry no
+ * `responseId` (server-initiated, no correlation needed), and they
+ * have no return code (events are not requests so there is nothing
+ * to fail).
+ */
 export declare class OperationEvent {
     private eventCode;
     private parameters;
+    /**
+     * @param eventCode  Event code carried by the frame; usually a
+     *                   constant from {@link EventCode}.
+     * @param parameters Optional parameter bag. Defaults to `null`
+     *                   for events with no payload.
+     */
     constructor(eventCode: string, parameters?: GNHashtable);
+    /**
+     * Returns the event code that the SDK uses to look up
+     * registered handlers.
+     */
     getEventCode(): string;
+    /**
+     * Returns the event parameter bag, or `null` for parameter-less
+     * events.
+     *
+     * Typed handlers usually feed this through
+     * {@link ConverterService.deserializeObject} to obtain a
+     * strongly typed payload.
+     */
     getParameters(): GNHashtable;
+    /**
+     * Adds or replaces a single parameter on the existing parameter
+     * bag.
+     *
+     * Note that this method assumes the parameter bag is non-null —
+     * if the event was constructed without one, call
+     * {@link setParameters} first.
+     */
     setParameter(k: string, value: any): OperationEvent;
+    /**
+     * Replaces the entire parameter bag.
+     */
     setParameters(parameters: GNHashtable): OperationEvent;
+    /**
+     * Returns a debug-friendly summary used by the
+     * `[GN Socket EVENT]` log line.
+     */
     toString(): string;
 }