@xmobitea/gn-typescript-client 2.6.13 → 2.6.14

package/dist/runtime/common/GNData.d.ts

@@ -1,69 +1,437 @@
+/**
+ * Discriminated union of every value the GearN containers accept.
+ *
+ * `GNHashtable` and `GNArray` only ever store one of these shapes
+ * internally. Plain JavaScript objects and arrays handed to
+ * {@link GNHashtable.add} / {@link GNArray.add} are wrapped into the
+ * corresponding container by
+ * {@link GNData.createUseDataFromOriginData} before they are stored.
+ * Keeping the union narrow lets the serializer in
+ * {@link MessagePackConverterService} branch on a small, well-known
+ * set of types.
+ */
 type GNDataType = string | number | boolean | null | GNArray | GNHashtable;
+/**
+ * Common container contract shared by {@link GNHashtable} (string keys)
+ * and {@link GNArray} (numeric indexes).
+ *
+ * The two implementations differ only in their storage shape — both
+ * expose the same lookup, mutation and inspection methods. This
+ * interface exists so generic code (the SDK transports, the model
+ * (de)serialiser) can accept either container without branching.
+ */
 interface IGNData {
+    /** Removes every entry from the container. */
     clear(): void;
+    /**
+     * Removes the entry at the given key (hash table) or index (array).
+     *
+     * @returns `true` when an entry was removed, `false` when the key
+     *          / index did not exist.
+     */
     remove(k: string | number): boolean;
+    /** Returns the current number of stored entries. */
     count(): string | number;
+    /** Reads the entry as an opaque object reference. */
     getObject(k: string | number, def?: object): object;
+    /** Reads the entry as a boolean. */
     getBoolean(k: string | number, def?: boolean): boolean;
+    /** Reads the entry as a string. */
     getString(k: string | number, def?: string): string;
+    /** Reads the entry as a number. */
     getNumber(k: string | number, def?: number): number;
+    /** Reads the entry as a {@link GNHashtable}. */
     getGNHashtable(k: string | number, def?: GNHashtable): GNHashtable;
+    /** Reads the entry as a {@link GNArray}. */
     getGNArray(k: string | number, def?: GNArray): GNArray;
 }
+/**
+ * Abstract base class for the GearN data containers.
+ *
+ * Concrete subclasses ({@link GNHashtable}, {@link GNArray}) provide
+ * the storage shape; this base class supplies:
+ * - the typed `get*` accessors that delegate to the abstract
+ *   {@link get} hook;
+ * - the conversion bridge between plain JavaScript values and the
+ *   internal {@link GNDataType} representation
+ *   ({@link createUseDataFromOriginData},
+ *   {@link createDataFromUseData});
+ * - the abstract `clear`, `remove`, `count`, `toData` contract every
+ *   container must implement.
+ *
+ * Why the indirection: the SDK accepts both bare JavaScript objects /
+ * arrays and `GNHashtable` / `GNArray` instances at every public API
+ * surface. By normalising everything to the `GN*` containers as soon
+ * as a value is stored, the rest of the SDK (serialisers,
+ * transports, network layer) only ever has to deal with the `GN*`
+ * shape.
+ */
 export declare abstract class GNData implements IGNData {
+    /**
+     * Reads the raw stored value at `k`.
+     *
+     * Implemented by each concrete container with the appropriate
+     * lookup logic (string-keyed map for {@link GNHashtable},
+     * indexed array for {@link GNArray}). Returns `def` when the
+     * lookup misses so the typed `get*` helpers below can stay
+     * branchless.
+     *
+     * @param k    Key (string for hash table) or index (number for
+     *             array).
+     * @param def  Fallback value returned when the entry is missing
+     *             or `null`.
+     * @returns The stored value cast to `T`, or `def` when not found.
+     */
     protected get<T>(k: string | number, def?: T): T;
+    /** Removes every entry from the container. */
     abstract clear(): void;
+    /**
+     * Removes the entry at `k`.
+     *
+     * @returns `true` when an entry was removed, `false` when the key
+     *          / index did not exist.
+     */
     abstract remove(k: string | number): boolean;
+    /** Returns the current number of stored entries. */
     abstract count(): string | number;
+    /**
+     * Reads the entry at `k` as a boolean.
+     *
+     * @param k    Key or index.
+     * @param def  Returned when the entry is missing or `null`.
+     * @returns The stored boolean, or `def` when not found. The value
+     *          is **not** coerced — if the entry actually holds a
+     *          number or string the cast performs no validation.
+     */
     getBoolean(k: string | number, def?: boolean): boolean;
+    /**
+     * Reads the entry at `k` as an opaque object reference.
+     *
+     * Use this when you only care about presence / identity of the
+     * stored value — for typed access prefer {@link getGNHashtable}
+     * or {@link getGNArray}.
+     *
+     * @param k    Key or index.
+     * @param def  Returned when the entry is missing or `null`.
+     */
     getObject(k: string | number, def?: object): object;
+    /**
+     * Reads the entry at `k` as a string.
+     *
+     * @param k    Key or index.
+     * @param def  Returned when the entry is missing or `null`.
+     */
     getString(k: string | number, def?: string): string;
+    /**
+     * Reads the entry at `k` as a number.
+     *
+     * @param k    Key or index.
+     * @param def  Returned when the entry is missing or `null`.
+     */
     getNumber(k: string | number, def?: number): number;
+    /**
+     * Reads the entry at `k` as a nested {@link GNHashtable}.
+     *
+     * @param k    Key or index.
+     * @param def  Returned when the entry is missing or `null`.
+     */
     getGNHashtable(k: string | number, def?: GNHashtable): GNHashtable;
+    /**
+     * Reads the entry at `k` as a nested {@link GNArray}.
+     *
+     * @param k    Key or index.
+     * @param def  Returned when the entry is missing or `null`.
+     */
     getGNArray(k: string | number, def?: GNArray): GNArray;
+    /**
+     * Wraps a plain JavaScript object as a {@link GNHashtable}.
+     *
+     * Iterates `Object.keys(value)` (own enumerable string keys) and
+     * recursively normalises each value through
+     * {@link createUseDataFromOriginData}. Symbol keys, non-enumerable
+     * properties and prototype-chain entries are ignored — the
+     * GearN wire format only supports plain string-keyed objects.
+     */
     private static createGNHashtableFromObject;
+    /**
+     * Wraps a plain JavaScript array as a {@link GNArray}.
+     *
+     * Iterates the indexed slots in order and normalises each entry
+     * through {@link createUseDataFromOriginData}. Sparse arrays are
+     * compacted because the loop iterates by index.
+     */
     private static createGNArrayFromArray;
+    /**
+     * Normalises a raw JavaScript value into the GearN container
+     * representation.
+     *
+     * Mapping rules:
+     * - `null` / `undefined` → `null`.
+     * - `string` / `number` / `boolean` → returned unchanged.
+     * - Existing `GNArray` / `GNHashtable` instance → returned unchanged.
+     * - Plain `Array` → recursively wrapped as `GNArray`.
+     * - Any other `object` → recursively wrapped as `GNHashtable`.
+     * - Anything else (e.g. `function`, `symbol`) → `null`.
+     *
+     * Used internally by every container `add(...)` call so the
+     * stored representation is always one of the {@link GNDataType}
+     * union members.
+     */
     protected static createUseDataFromOriginData(value: any): GNDataType;
+    /**
+     * Reverse of {@link createUseDataFromOriginData} — unwraps a
+     * stored container value back into plain JavaScript data so it
+     * can be handed to a non-GearN consumer (`JSON.stringify`,
+     * MsgPack codec, application code).
+     *
+     * Mapping rules:
+     * - `null` → `null`.
+     * - {@link GNArray} → plain array via `toData()`.
+     * - {@link GNHashtable} → plain object via `toData()`.
+     * - Primitive → returned unchanged.
+     */
     protected static createDataFromUseData(value: GNDataType): any;
+    /**
+     * Returns a plain JavaScript representation of the container.
+     *
+     * Concrete subclasses implement this by walking their stored
+     * entries and calling {@link createDataFromUseData} on each. The
+     * result is safe to feed to `JSON.stringify` or to the
+     * MessagePack encoder.
+     */
     abstract toData(): any;
 }
+/**
+ * Fluent builder for {@link GNHashtable}.
+ *
+ * Lets caller code accumulate key/value pairs in a chainable form and
+ * materialise the resulting hash table in a single call:
+ *
+ * ```ts
+ * const params = GNHashtable.builder()
+ *     .add("username", "alice")
+ *     .add("password", "p@ssword")
+ *     .build();
+ * ```
+ *
+ * The builder stores raw values; conversion through
+ * {@link GNData.createUseDataFromOriginData} happens during
+ * {@link build} when entries are pushed into the new
+ * {@link GNHashtable}.
+ */
 export declare class GNHashtableBuilder {
     private dict;
+    /**
+     * Stores `value` under `k`, replacing any previous value at the
+     * same key.
+     *
+     * @returns The same builder instance for chaining.
+     */
     add(k: string, value: any): GNHashtableBuilder;
+    /**
+     * Copies every own-enumerable string key from `dict` into the
+     * builder. Equivalent to looping over the dictionary and calling
+     * {@link add} for each entry.
+     *
+     * @param dict Source object. Symbol keys, non-enumerable
+     *             properties and prototype entries are ignored.
+     * @returns The same builder instance for chaining.
+     */
     addAll(dict: {
         [k: string]: any;
     }): this;
+    /**
+     * Creates an empty builder. Prefer the static factory
+     * {@link GNHashtable.builder} from caller code.
+     */
     constructor();
+    /**
+     * Materialises a fresh {@link GNHashtable} that contains every
+     * accumulated entry.
+     *
+     * The builder remains usable after `build()` — calling it twice
+     * yields two independent hash tables seeded from the same data.
+     */
     build(): GNHashtable;
 }
+/**
+ * String-keyed container used as the canonical "object-shaped" payload
+ * inside the GearN SDK.
+ *
+ * Every request payload, every response parameter bag and every nested
+ * model field that is decoded as `GNHashtable` flows through this
+ * class. It mirrors the .NET `Hashtable` API of the original GearN
+ * client SDK so cross-platform documentation stays consistent.
+ *
+ * Storage shape: a plain `{ [k: string]: GNDataType }` dictionary.
+ * Iteration order matches `Object.keys(...)` (insertion order for
+ * string keys, per the ES2015 spec).
+ */
 export declare class GNHashtable extends GNData {
     private dict;
+    /** Removes every key from the hash table. */
     clear(): void;
+    /**
+     * Removes the entry stored under `k`.
+     *
+     * @returns `true` when a value was removed, `false` when the
+     *          key was absent.
+     */
     remove(k: string): boolean;
+    /** Returns the current number of stored keys. */
     count(): number;
+    /**
+     * Returns whether `k` is currently present.
+     *
+     * Uses `hasOwnProperty` to avoid false positives from
+     * inherited prototype properties.
+     */
     containsKey(k: string): boolean;
+    /**
+     * Returns the stored value at `k` cast to `T`, or `def` when the
+     * key is missing / the stored value is `null`.
+     */
     protected get<T>(k: string, def?: T): T;
+    /**
+     * Stores `value` under `k`.
+     *
+     * The value is normalised through
+     * {@link GNData.createUseDataFromOriginData} before being stored,
+     * so plain objects become nested `GNHashtable` instances and
+     * plain arrays become nested {@link GNArray} instances.
+     */
     add(k: string, value: any): void;
+    /**
+     * Returns a plain `{ [k: string]: any }` representation of the
+     * hash table, recursively unwrapping nested containers.
+     *
+     * Useful when the value is about to be handed to a non-GearN
+     * consumer such as `JSON.stringify` or the MessagePack codec.
+     */
     toData(): {};
+    /**
+     * Returns a fluent {@link GNHashtableBuilder} pre-bound to a
+     * fresh empty backing dictionary.
+     *
+     * Equivalent to `new GNHashtableBuilder()` but reads more
+     * naturally at the call site:
+     *
+     * ```ts
+     * GNHashtable.builder().add("k", 1).build();
+     * ```
+     */
     static builder(): GNHashtableBuilder;
+    /**
+     * Returns a JSON dump of the underlying dictionary.
+     *
+     * Intended for log lines (`GNDebug.log`) and unit-test
+     * assertions, not for wire serialisation. Nested containers are
+     * serialised by their own `toString` / `toJSON` machinery, which
+     * for `GNHashtable` recurses back into this method.
+     */
     toString(): string;
 }
+/**
+ * Fluent builder for {@link GNArray}.
+ *
+ * Lets caller code accumulate values in a chainable form and
+ * materialise the resulting array in a single `build()` call:
+ *
+ * ```ts
+ * const arr = GNArray.builder().add(1).add(2).addAll([3, 4]).build();
+ * ```
+ */
 export declare class GNArrayBuilder {
     private array;
+    /**
+     * Appends `value` to the builder.
+     *
+     * @returns The same builder instance for chaining.
+     */
     add(value: any): GNArrayBuilder;
+    /**
+     * Appends every entry from `array` in order.
+     *
+     * @param array Source values. Each entry is forwarded through
+     *              {@link add}.
+     * @returns The same builder instance for chaining.
+     */
     addAll(array: any[]): GNArrayBuilder;
+    /**
+     * Materialises a fresh {@link GNArray} that contains every
+     * accumulated value.
+     *
+     * The builder remains usable after `build()` — calling it twice
+     * yields two independent arrays seeded from the same data.
+     */
     build(): GNArray;
+    /**
+     * Creates an empty builder. Prefer the static factory
+     * {@link GNArray.builder} from caller code.
+     */
     constructor();
 }
+/**
+ * Numerically-indexed container used as the canonical "array-shaped"
+ * payload inside the GearN SDK.
+ *
+ * Mirrors the .NET `ArrayList` API of the original client SDK and is
+ * the wire-level representation for any field decorated with
+ * {@link GNArrayDataMember} or returned by the backend as a list.
+ *
+ * Storage shape: a plain `Array<GNDataType>` honouring its declared
+ * iteration order.
+ */
 export declare class GNArray extends GNData {
     private array;
+    /** Removes every value from the array. */
     clear(): void;
+    /**
+     * Removes the value at index `k` and shifts the tail forward by
+     * one position.
+     *
+     * @returns `true` when an entry was removed, `false` when the
+     *          index was out of range.
+     */
     remove(k: number): boolean;
+    /** Returns the number of stored values. */
     count(): number;
+    /**
+     * Returns the value at index `k` cast to `T`, or `def` when the
+     * index is out of range or the slot is `null`.
+     *
+     * Out-of-range indexes return `null` instead of `def` because the
+     * caller's intent there is usually "treat as missing without
+     * fallback".
+     */
     protected get<T>(k: number, def?: T): T;
+    /**
+     * Appends `value` to the array.
+     *
+     * The value is normalised through
+     * {@link GNData.createUseDataFromOriginData} before being stored,
+     * so plain objects and arrays become nested containers.
+     */
     add(value: any): void;
+    /**
+     * Returns a plain `any[]` representation of the array,
+     * recursively unwrapping nested containers.
+     */
     toData(): any[];
+    /**
+     * Returns a fluent {@link GNArrayBuilder} pre-bound to a fresh
+     * empty backing array.
+     *
+     * Equivalent to `new GNArrayBuilder()` but reads more naturally
+     * at the call site.
+     */
     static builder(): GNArrayBuilder;
+    /**
+     * Returns a JSON dump of the underlying array.
+     *
+     * Intended for log lines and unit-test assertions, not for wire
+     * serialisation.
+     */
     toString(): string;
 }
 export {};