mftsccs-node 0.2.23 → 0.2.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +41 -29
  2. package/dist/bundle.js +1 -1
  3. package/dist/bundle.mjs +1 -0
  4. package/dist/types/Api/Create/CreateTheConnectionApi.d.ts +4 -9
  5. package/dist/types/Api/GetAllConcepts.d.ts +0 -4
  6. package/dist/types/Api/GetAllLinkerConnectionsFromTheConcept.d.ts +1 -1
  7. package/dist/types/Api/GetAllLinkerConnectionsToTheConcept.d.ts +1 -1
  8. package/dist/types/Api/GetAllPrefetchConnections.d.ts +0 -3
  9. package/dist/types/Api/GetConnections/GetConnectionsBetweenApi.d.ts +8 -0
  10. package/dist/types/Api/GetReservedConnectionIds.d.ts +1 -1
  11. package/dist/types/Api/RecursiveSearch.d.ts +1 -1
  12. package/dist/types/Api/Search/FreeschemaQueryApi.d.ts +6 -5
  13. package/dist/types/Api/Search/Search.d.ts +4 -3
  14. package/dist/types/Api/Search/SearchInternalApi.d.ts +5 -4
  15. package/dist/types/Api/Search/SearchLinkMultipleApi.d.ts +4 -4
  16. package/dist/types/Api/Search/SearchWithLinker.d.ts +5 -4
  17. package/dist/types/Api/SearchConcept/GetConceptByCharacterAndCategoryApi.d.ts +3 -2
  18. package/dist/types/Api/SearchConcept/GetConceptByCharacterAndCategoryDirect.d.ts +3 -2
  19. package/dist/types/Api/View/ViewInternalDataApi.d.ts +3 -4
  20. package/dist/types/DataStructures/BaseUrl.d.ts +5 -0
  21. package/dist/types/DataStructures/ConceptData.d.ts +14 -5
  22. package/dist/types/DataStructures/FetchConnection.d.ts +21 -0
  23. package/dist/types/DataStructures/ReservedIds.d.ts +11 -16
  24. package/dist/types/DataStructures/Search/FreeschemaQuery.d.ts +1 -0
  25. package/dist/types/DataStructures/Transaction/Transaction.d.ts +23 -0
  26. package/dist/types/DataStructures/User/UserBinaryTree.d.ts +1 -119
  27. package/dist/types/DataStructures/User/UserNode.d.ts +4 -146
  28. package/dist/types/Database/NoIndexDb.d.ts +32 -36
  29. package/dist/types/Services/Common/DecodeCountInfo.d.ts +4 -3
  30. package/dist/types/Services/Common/ErrorPosting.d.ts +5 -7
  31. package/dist/types/Services/CreateConnectionBetweenTwoConcepts.d.ts +4 -3
  32. package/dist/types/Services/CreateTheComposition.d.ts +2 -2
  33. package/dist/types/Services/CreateTheConnection.d.ts +9 -4
  34. package/dist/types/Services/CreateTheConnectionGeneral.d.ts +4 -4
  35. package/dist/types/Services/GetDataFromIndexDb.d.ts +8 -8
  36. package/dist/types/Services/Http/HttpClient.service.d.ts +7 -0
  37. package/dist/types/Services/MakeTheTimestamp.d.ts +2 -2
  38. package/dist/types/Services/PatchComposition.d.ts +10 -15
  39. package/dist/types/Services/UpdateComposition.d.ts +1 -1
  40. package/dist/types/app.d.ts +21 -21
  41. package/package.json +12 -1
@@ -18,7 +18,8 @@
18
18
  * @param token - Authentication token for authorized access
19
19
  * @param inpage - Number of results per page (defaults to 10)
20
20
  * @param page - Page number for pagination, starting from 1 (defaults to 1)
21
- * @returns Promise resolving to an array of matching concepts, or empty array on error
21
+ * @returns Promise resolving to an array of matching concepts. A valid empty result is returned as an empty array.
22
+ * @throws Will throw if the request fails or the backend returns a non-OK response.
22
23
  *
23
24
  * @example
24
25
  * ```typescript
@@ -51,9 +52,9 @@
51
52
  * simple search operations. For more complex queries, consider using FreeschemaQueryApi.
52
53
  *
53
54
  * Error handling:
54
- * - HTTP errors are handled via HandleHttpError and logged
55
+ * - HTTP errors are handled via HandleHttpError and thrown
55
56
  * - Network errors are caught, logged, and re-thrown
56
- * - Returns empty array on HTTP errors, throws exception on network errors
57
+ * - Empty arrays represent valid empty results, not failed requests
57
58
  *
58
59
  * Pagination:
59
60
  * - Results are paginated server-side
@@ -7,7 +7,7 @@
7
7
  * @module Api/Search/SearchInternalApi
8
8
  * @see https://documentation.freeschema.com for internal composition structure and search patterns
9
9
  */
10
- import { SearchStructure } from "../../app";
10
+ import { SearchStructure } from "../../DataStructures/Search/SearchStructure";
11
11
  /**
12
12
  * Searches for concepts within internal (nested) compositions with authentication.
13
13
  * This function enables searching for concepts that are part of internal compositions,
@@ -16,7 +16,8 @@ import { SearchStructure } from "../../app";
16
16
  *
17
17
  * @param search - SearchStructure object containing all search parameters including composition, internal composition, type, search text, and pagination
18
18
  * @param token - Optional authentication token for authorized access (defaults to empty string for public queries)
19
- * @returns Promise resolving to an array of matching concepts from the internal composition, or empty array on error
19
+ * @returns Promise resolving to an array of matching concepts from the internal composition. A valid empty result is returned as an empty array.
20
+ * @throws Will throw if the request fails or the backend returns a non-OK response.
20
21
  *
21
22
  * @example
22
23
  * ```typescript
@@ -56,9 +57,9 @@ import { SearchStructure } from "../../app";
56
57
  * - Filtering results within specific composition contexts
57
58
  *
58
59
  * Error handling:
59
- * - HTTP errors are logged with status and handled via HandleHttpError
60
+ * - HTTP errors are handled via HandleHttpError and thrown
60
61
  * - Network errors are caught, logged, and re-thrown
61
- * - Returns empty array on HTTP errors to prevent null reference issues
62
+ * - Empty arrays represent valid empty results, not failed requests
62
63
  *
63
64
  * Query construction:
64
65
  * - All parameters are URL-encoded as query strings
@@ -17,7 +17,8 @@ import { SearchQuery } from '../../DataStructures/SearchQuery';
17
17
  *
18
18
  * @param searchQuery - Array of SearchQuery objects, each containing search parameters for a specific query
19
19
  * @param token - Optional authentication token for authorized access (defaults to empty string for public queries)
20
- * @returns Promise resolving to an array of search results (one result set per query), or empty array on error
20
+ * @returns Promise resolving to an array of search results, one result set per query. A valid empty result is returned as an empty array.
21
+ * @throws Will throw if the request fails or the backend returns a non-OK response.
21
22
  *
22
23
  * @example
23
24
  * ```typescript
@@ -74,10 +75,9 @@ import { SearchQuery } from '../../DataStructures/SearchQuery';
74
75
  * - Atomic execution of all queries
75
76
  *
76
77
  * Error handling:
77
- * - HTTP errors are logged with status and handled via HandleHttpError
78
+ * - HTTP errors are handled via HandleHttpError and thrown
78
79
  * - Network errors are caught, logged, and re-thrown
79
- * - Returns empty array on HTTP errors to prevent null reference issues
80
- * - If any query fails, the entire operation returns an empty array
80
+ * - Empty arrays represent valid empty results, not failed requests
81
81
  *
82
82
  * Query execution:
83
83
  * - All queries are executed server-side
@@ -17,7 +17,8 @@ import { SearchQuery } from '../../DataStructures/SearchQuery';
17
17
  *
18
18
  * @param searchQuery - Array of SearchQuery objects defining search criteria and relationship paths to follow
19
19
  * @param token - Optional authentication token for authorized access (defaults to empty string for public queries)
20
- * @returns Promise resolving to an array of search results with linked concepts resolved, or empty array on error
20
+ * @returns Promise resolving to an array of search results with linked concepts resolved. A valid empty result is returned as an empty array.
21
+ * @throws Will throw if the request fails or the backend returns a non-OK response.
21
22
  *
22
23
  * @example
23
24
  * ```typescript
@@ -81,10 +82,10 @@ import { SearchQuery } from '../../DataStructures/SearchQuery';
81
82
  * - Ideal for reducing client-side data fetching complexity
82
83
  *
83
84
  * Error handling:
84
- * - HTTP errors are logged with status and handled via HandleHttpError
85
+ * - HTTP errors are handled via HandleHttpError and thrown
85
86
  * - Network errors are caught, logged, and re-thrown
86
- * - Returns empty array on HTTP errors to maintain consistent error handling
87
- * - Link resolution errors are handled gracefully server-side
87
+ * - Empty arrays represent valid empty results, not failed requests
88
+ * - Link resolution errors are handled by the backend response contract
88
89
  *
89
90
  * Use cases:
90
91
  * - Building detailed profile views with all related data
@@ -16,6 +16,7 @@ import { Concept } from "../../DataStructures/Concept";
16
16
  *
17
17
  * @param characterValue - The character string identifying the concept (e.g., "the_person", "john_doe")
18
18
  * @returns A promise that resolves to the matching Concept object, or a default concept if not found
19
+ * @throws Will throw if the request fails or the backend returns a non-OK response.
19
20
  *
20
21
  * @example
21
22
  * ```typescript
@@ -29,9 +30,9 @@ import { Concept } from "../../DataStructures/Concept";
29
30
  * ```
30
31
  *
31
32
  * @remarks
32
- * - Returns a default concept (id=0) if the concept is not found or an error occurs
33
+ * - Returns a default concept (id=0) if the concept is not found
33
34
  * - Automatically caches the retrieved concept in ConceptsData
34
- * - HTTP errors are handled through HandleHttpError but do not throw
35
+ * - HTTP errors are handled through HandleHttpError and thrown
35
36
  * - Errors are logged to console and re-thrown for caller handling
36
37
  *
37
38
  * @see GetConceptByCharacterAndCategoryDirectApi for searching with explicit category
@@ -18,6 +18,7 @@ import { Concept } from "./../../DataStructures/Concept";
18
18
  * @param characterValue - The character string identifying the concept (e.g., "john_doe", "building_a")
19
19
  * @param category_id - The specific category ID to search within
20
20
  * @returns A promise that resolves to the matching Concept object, or a default concept if not found
21
+ * @throws Will throw if the request fails or the backend returns a non-OK response.
21
22
  *
22
23
  * @example
23
24
  * ```typescript
@@ -36,10 +37,10 @@ import { Concept } from "./../../DataStructures/Concept";
36
37
  * @remarks
37
38
  * - Uses local caching (conceptCache) to prevent duplicate simultaneous requests
38
39
  * - Cache key is the concatenation of characterValue and category_id
39
- * - Returns a default concept (id=0) if the concept is not found or an error occurs
40
+ * - Returns a default concept (id=0) if the concept is not found
40
41
  * - Automatically caches the retrieved concept in ConceptsData for subsequent use
41
42
  * - Cache entries are cleaned up in the finally block after fetch completes
42
- * - HTTP errors are handled through HandleHttpError but do not throw
43
+ * - HTTP errors are handled through HandleHttpError and thrown
43
44
  * - Errors are logged with full diagnostic information including the endpoint URL
44
45
  *
45
46
  * @see GetConceptByCharacterAndCategoryApi for searching without explicit category
@@ -16,8 +16,8 @@
16
16
  * internal connection lists.
17
17
  *
18
18
  * @param ids - Array of concept IDs to retrieve internal data for
19
- * @returns A promise that resolves to a dictionary mapping concept IDs to their internal connections,
20
- * or an empty connection list if the request fails
19
+ * @returns A promise that resolves to a dictionary mapping concept IDs to their internal connections.
20
+ * @throws Will throw if the request fails or the backend returns a non-OK response.
21
21
  *
22
22
  * @example
23
23
  * ```typescript
@@ -40,8 +40,7 @@
40
40
  * @remarks
41
41
  * - Returns an object where keys are concept IDs and values are arrays of Connection objects
42
42
  * - Automatically fetches and caches all sub-concepts via GetConceptBulk
43
- * - Returns an empty connection list on error
44
- * - HTTP errors are handled through HandleHttpError but do not throw
43
+ * - HTTP errors are handled through HandleHttpError and thrown
45
44
  * - Requires authentication via GetRequestHeader
46
45
  * - Errors are logged to console and re-thrown for caller handling
47
46
  *
@@ -64,6 +64,11 @@ export declare class BaseUrl {
64
64
  * @returns {string} The user connections retrieval API endpoint
65
65
  */
66
66
  static GetAllConnectionsOfUserUrl(): string;
67
+ /**
68
+ * Returns the URL for retrieving connection IDs matching connection filters.
69
+ * @returns {string} The connection filtering API endpoint
70
+ */
71
+ static GetConnectionsBetweenUrl(): string;
67
72
  /**
68
73
  * Returns the URL for retrieving all connections of a composition.
69
74
  * @returns {string} The composition connections retrieval API endpoint
@@ -38,10 +38,19 @@ export declare class ConceptsData {
38
38
  /** Legacy array storage for concepts (deprecated in favor of tree structures) */
39
39
  static conceptsArray: Concept[];
40
40
  /**
41
- * NPC (Non-Persistent Concepts) cache for temporarily tracking accessed concept IDs.
42
- * Limited to 10 entries for memory management.
41
+ * NPC (Non-Persistent Concepts) cache for concept IDs that are currently in cooldown.
43
42
  */
44
43
  static NPC: number[];
44
+ /**
45
+ * Per-NPC cooldown state. Each failed backend lookup increases the cooldown by
46
+ * 30 seconds: first miss = 30s, second miss = 60s, third miss = 90s, etc.
47
+ */
48
+ static NPCMeta: Map<number, {
49
+ attempts: number;
50
+ expiresAt: number;
51
+ }>;
52
+ static NPC_BACKOFF_SECONDS: number;
53
+ static RemoveExpiredNpc(now?: number): void;
45
54
  /** Dictionary-style storage for quick concept lookups by ID */
46
55
  static conceptDictionary: Concept[];
47
56
  /**
@@ -61,7 +70,7 @@ export declare class ConceptsData {
61
70
  static CheckContains(concept: Concept): boolean;
62
71
  /**
63
72
  * Adds a concept ID to the Non-Persistent Concepts (NPC) cache.
64
- * Used for tracking recently accessed concepts. Automatically clears when exceeding 10 entries.
73
+ * Used for tracking recently missed concepts with a growing retry cooldown.
65
74
  *
66
75
  * @param {number} id - The concept ID to add to NPC cache
67
76
  *
@@ -72,10 +81,10 @@ export declare class ConceptsData {
72
81
  */
73
82
  static AddNpc(id: number): void;
74
83
  /**
75
- * Checks if a concept ID exists in the NPC cache.
84
+ * Checks if a concept ID exists in the NPC cache and is still inside its cooldown.
76
85
  *
77
86
  * @param {number} id - The concept ID to check
78
- * @returns {boolean} True if the ID is in the NPC cache, false otherwise
87
+ * @returns {boolean} True if the ID is currently in NPC cooldown, false otherwise
79
88
  *
80
89
  * @example
81
90
  * ```typescript
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Request/response shape for POST /api/get-connection-between.
3
+ *
4
+ * Use only the fields relevant to the query and leave the rest at their
5
+ * zero/empty defaults. The backend resolves typeId from type when typeId is 0.
6
+ */
7
+ export interface FetchConnection {
8
+ ofTheConceptId: number;
9
+ toTheConceptId: number;
10
+ typeId: number;
11
+ type: string;
12
+ oldType: string;
13
+ reverse: boolean;
14
+ isComposition: boolean;
15
+ connectionIds: number[];
16
+ }
17
+ export type FetchConnectionQuery = Omit<FetchConnection, 'connectionIds'>;
18
+ /**
19
+ * Builds a complete FetchConnection request object from a partial query.
20
+ */
21
+ export declare function buildFetchConnection(query: Partial<FetchConnectionQuery>): FetchConnection;
@@ -24,6 +24,7 @@
24
24
  export declare class ReservedIds {
25
25
  /** Pool of reserved concept IDs */
26
26
  static ids: number[];
27
+ private static pendingFetch;
27
28
  /**
28
29
  * Gets the next available reserved ID from the pool.
29
30
  * Automatically refills the pool if it has fewer than 10 IDs.
@@ -77,21 +78,13 @@ export declare class ReservedIds {
77
78
  export declare class ReservedConnectionIds {
78
79
  /** Pool of reserved connection IDs */
79
80
  static connectionIds: number[];
81
+ private static pendingFetch;
80
82
  /**
81
83
  * Gets the next available reserved connection ID from the pool.
82
- * Automatically refills the pool if it has fewer than 10 IDs.
84
+ * Triggers a background refill when the pool is low, and waits for a fetch
85
+ * if the pool is completely empty. Only one fetch is in-flight at a time.
83
86
  *
84
87
  * @returns {Promise<number>} A unique reserved connection ID
85
- *
86
- * @example
87
- * ```typescript
88
- * const id = await ReservedConnectionIds.getId();
89
- * const connection = new Connection(id, ...);
90
- * ```
91
- *
92
- * @remarks
93
- * Uses FIFO (first in, first out) to retrieve IDs.
94
- * Triggers a backend call to GetReservedConnectionIds when pool is low.
95
88
  */
96
89
  static getId(): Promise<number>;
97
90
  /**
@@ -99,13 +92,15 @@ export declare class ReservedConnectionIds {
99
92
  *
100
93
  * @param {number} id - The ID to add to the pool
101
94
  *
102
- * @example
103
- * ```typescript
104
- * ReservedConnectionIds.AddId(456);
105
- * ```
106
- *
107
95
  * @remarks
108
96
  * Prevents duplicate IDs from being added to the pool.
109
97
  */
110
98
  static AddId(id: number): void;
99
+ /**
100
+ * Pre-fills the pool with at least `needed` IDs in a single API call.
101
+ * Call this before a parallel batch so getId() never has to wait mid-flight.
102
+ *
103
+ * @param {number} needed - Total IDs required for the upcoming batch
104
+ */
105
+ static warmUp(needed: number): Promise<void>;
111
106
  }
@@ -184,4 +184,5 @@ export declare class FreeschemaQuery {
184
184
  * @default false
185
185
  */
186
186
  isOldConnectionType: boolean;
187
+ usePipelineQuery: boolean;
187
188
  }
@@ -4,6 +4,7 @@
4
4
  */
5
5
  import { Concept } from "../Concept";
6
6
  import { Connection } from "../Connection";
7
+ import { FetchConnectionQuery } from "../FetchConnection";
7
8
  /**
8
9
  * Manages transactional operations for concepts and connections.
9
10
  * This class provides ACID-like transaction capabilities for creating and managing
@@ -69,6 +70,14 @@ export declare class Transaction {
69
70
  * @default true
70
71
  */
71
72
  protected success: boolean;
73
+ /**
74
+ * Connection IDs queued for deletion when the transaction commits.
75
+ * Rollback clears this list without touching the backend.
76
+ *
77
+ * @protected
78
+ * @type {number[]}
79
+ */
80
+ protected pendingConnectionDeletions: number[];
72
81
  /**
73
82
  * Creates a new Transaction instance.
74
83
  * Generates a unique transaction ID for tracking purposes.
@@ -154,6 +163,20 @@ export declare class Transaction {
154
163
  * ```
155
164
  */
156
165
  commitTransaction(): Promise<void>;
166
+ /**
167
+ * Queues connections matching one query for deletion on commit.
168
+ *
169
+ * Nothing is deleted until commitTransaction() is called. Calling
170
+ * rollbackTransaction() discards the queued IDs.
171
+ */
172
+ DeleteConnectionsBetween(query: Partial<FetchConnectionQuery>): Promise<number[]>;
173
+ /**
174
+ * Queues connections matching multiple queries for deletion on commit.
175
+ *
176
+ * The queries are resolved in one API call, then their connection IDs are
177
+ * merged into this transaction's pending deletion queue.
178
+ */
179
+ DeleteConnectionsBetweenBulk(queries: Partial<FetchConnectionQuery>[]): Promise<number[]>;
157
180
  /**
158
181
  * Creates a new instance concept within the transaction.
159
182
  * The concept represents a data instance of a specified type with associated metadata.
@@ -1,132 +1,14 @@
1
- /**
2
- * @fileoverview Binary tree for managing user-specific concepts and connections.
3
- * This module provides a composite-key based tree for efficient user and session-based data storage.
4
- * @module DataStructures/User/UserBinaryTree
5
- */
6
1
  import { LConcept } from "../../DataStructures/Local/LConcept";
7
2
  import { UserNode } from "./UserNode";
8
3
  import { LConnection } from "../Local/LConnection";
9
- /**
10
- * Binary tree data structure for managing user-specific data with composite keys.
11
- *
12
- * @remarks
13
- * This class implements an AVL tree that uses composite keys (userId + sessionId + randomizer)
14
- * to organize user-specific concepts and connections. The composite key enables efficient
15
- * organization and retrieval of data by user, session, and application context.
16
- *
17
- * @example
18
- * ```typescript
19
- * const concept = new LConcept(123, "example", 5);
20
- * UserBinaryTree.addConceptToTree(concept, 42, 999);
21
- * const node = await UserBinaryTree.getNodeFromTree(42, 999, 123);
22
- * ```
23
- */
24
4
  export declare class UserBinaryTree {
25
- /**
26
- * The root node of the user data binary tree.
27
- * Null if the tree is empty.
28
- */
29
- static root: UserNode | null;
30
- /**
31
- * Creates a composite key from user ID, session ID, and randomizer.
32
- *
33
- * @param userId - The user ID
34
- * @param sessionId - The session ID
35
- * @param randomizer - Additional identifier (defaults to 999)
36
- * @returns A 12-character hexadecimal composite key
37
- *
38
- * @remarks
39
- * The composite key is formed by concatenating three 4-digit hexadecimal values:
40
- * userHex (4 chars) + sessionHex (4 chars) + randomizerHex (4 chars) = 12 chars total.
41
- * This enables unique identification of data across users, sessions, and applications.
42
- *
43
- * @example
44
- * ```typescript
45
- * const key = UserBinaryTree.compositeKey(42, 999, 123);
46
- * // Returns something like "002A03E7007B"
47
- * ```
48
- */
5
+ static nodeMap: Map<string, UserNode>;
49
6
  static compositeKey(userId: number, sessionId: number, randomizer?: number): string;
50
- /**
51
- * Adds a user node to the binary tree.
52
- *
53
- * @param node - The UserNode to be added to the tree
54
- *
55
- * @remarks
56
- * If the tree is empty, the provided node becomes the root.
57
- * Otherwise, the node is inserted using the AVL tree balancing algorithm.
58
- */
59
- static addNodeToTree(node: UserNode): UserNode | undefined;
60
- /**
61
- * Waits for user data to be loaded into the tree.
62
- *
63
- * @returns A promise that resolves with "done" when data is loaded, or rejects with "not" after 25 seconds
64
- */
65
7
  static waitForDataToLoad(): Promise<unknown>;
66
- /**
67
- * Periodically checks if user data has been loaded.
68
- *
69
- * @param resolve - The promise resolve function to call when data is loaded
70
- */
71
8
  static checkFlag(resolve: any): any;
72
- /**
73
- * Creates a node from a concept and adds it to the user tree.
74
- *
75
- * @param concept - The LConcept object to be added
76
- * @param userId - The user ID
77
- * @param sessionId - The session ID (defaults to 999)
78
- *
79
- * @remarks
80
- * Uses the concept's applicationId as the randomizer in the composite key.
81
- */
82
9
  static addConceptToTree(concept: LConcept, userId: number, sessionId?: number): void;
83
- /**
84
- * Creates a node from a connection and adds it to the user tree.
85
- *
86
- * @param connection - The LConnection object to be added
87
- * @param userId - The user ID
88
- * @param sessionId - The session ID (defaults to 999)
89
- *
90
- * @remarks
91
- * Uses the connection's applicationId as the randomizer in the composite key.
92
- */
93
10
  static addConnectionToTree(connection: LConnection, userId: number, sessionId?: number): void;
94
- /**
95
- * Retrieves a node from the tree using composite key components.
96
- *
97
- * @param userId - The user ID
98
- * @param sessionId - The session ID
99
- * @param randomizer - Additional identifier (defaults to 999)
100
- * @returns The UserNode if found, null otherwise
101
- *
102
- * @remarks
103
- * Constructs a composite key from the parameters and performs a binary search.
104
- */
105
11
  static getNodeFromTree(userId: number, sessionId: number, randomizer?: number): Promise<UserNode | null>;
106
- /**
107
- * Removes a node from the tree using composite key components.
108
- *
109
- * @param userId - The user ID
110
- * @param sessionId - The session ID (defaults to 999)
111
- * @param randomizer - Additional identifier (defaults to 999)
112
- *
113
- * @remarks
114
- * Constructs a composite key and removes the matching node while maintaining AVL balance.
115
- */
116
12
  static removeNodeFromTree(userId: number, sessionId?: number, randomizer?: number): Promise<void>;
117
- /**
118
- * Counts the total number of nodes in the tree.
119
- *
120
- * @returns The total number of user nodes in the tree
121
- *
122
- * @remarks
123
- * Recursively traverses the entire tree to count all nodes. Returns 0 if the tree is empty.
124
- *
125
- * @example
126
- * ```typescript
127
- * const count = UserBinaryTree.countNumberOfNodes();
128
- * console.log(`Tree contains ${count} user data nodes`);
129
- * ```
130
- */
131
13
  static countNumberOfNodes(): number;
132
14
  }
@@ -1,150 +1,8 @@
1
- /**
2
- * @fileoverview Node implementation for the UserBinaryTree.
3
- * This module provides the UserNode class for storing user-specific concepts and connections.
4
- * @module DataStructures/User/UserNode
5
- */
6
1
  import { LConcept } from "../Local/LConcept";
7
2
  import { LConnection } from "../Local/LConnection";
8
- /**
9
- * Represents a node in the user binary tree that stores both concepts and connections.
10
- *
11
- * @remarks
12
- * UserNode implements an AVL tree node that can store multiple concepts and connections
13
- * for a given composite key (userId + sessionId + randomizer). This allows efficient
14
- * storage and retrieval of all user data associated with a specific key combination.
15
- *
16
- * @example
17
- * ```typescript
18
- * const concept = new LConcept(123, "example", 5);
19
- * const connection = new LConnection(456, 1, 2, 3, 4, 5);
20
- * const node = new UserNode("compositeKey", concept, connection, null, null);
21
- * ```
22
- */
23
3
  export declare class UserNode {
24
- /**
25
- * The composite key used for tree ordering.
26
- * Typically a hexadecimal string combining userId, sessionId, and randomizer.
27
- */
28
- key: any;
29
- /**
30
- * Array of connections stored in this node.
31
- * Multiple connections can be associated with the same key.
32
- */
33
- connectionValue: LConnection[];
34
- /**
35
- * Array of concepts stored in this node.
36
- * Multiple concepts can be associated with the same key.
37
- */
38
- value: LConcept[];
39
- /**
40
- * Reference to the left child node.
41
- */
42
- leftNode: UserNode | null;
43
- /**
44
- * Reference to the right child node.
45
- */
46
- rightNode: UserNode | null;
47
- /**
48
- * The height of this node in the tree.
49
- * Used for AVL tree balancing calculations.
50
- */
51
- height: number;
52
- /**
53
- * Creates a new UserNode.
54
- *
55
- * @param key - The composite key for tree ordering
56
- * @param value - The LConcept to store (added if ID > 0)
57
- * @param connectionValue - The LConnection to store (added if ID > 0)
58
- * @param leftNode - The left child node (or null)
59
- * @param rightNode - The right child node (or null)
60
- *
61
- * @remarks
62
- * Only adds concepts and connections with valid (> 0) IDs to their respective arrays.
63
- *
64
- * @example
65
- * ```typescript
66
- * const node = new UserNode("compositeKey", concept, connection, null, null);
67
- * ```
68
- */
69
- constructor(key: any, value: LConcept, connectionValue: LConnection, leftNode: UserNode | null, rightNode: UserNode | null);
70
- /**
71
- * Adds a new node to the tree with AVL balancing.
72
- *
73
- * @param passedNode - The node to be added
74
- * @param node - The current node being evaluated
75
- * @param height - The height of the current node
76
- * @returns The root node after insertion and balancing
77
- *
78
- * @remarks
79
- * Implements AVL tree insertion. When a node with the same key exists,
80
- * the new node's concepts and connections are added to the existing node's arrays.
81
- */
82
- addNode(passedNode: UserNode, node: UserNode | null, height: number): UserNode | null;
83
- /**
84
- * Performs a right rotation on the given node for AVL balancing.
85
- *
86
- * @param y - The node to rotate right
87
- * @returns The new root node after rotation
88
- */
89
- rightRotate(y: UserNode | null): UserNode | null;
90
- /**
91
- * Performs a left rotation on the given node for AVL balancing.
92
- *
93
- * @param x - The node to rotate left
94
- * @returns The new root node after rotation
95
- */
96
- leftRotate(x: UserNode | null): UserNode | null;
97
- /**
98
- * Gets the height of a node.
99
- *
100
- * @param node - The node to get the height from
101
- * @returns The height of the node, or 0 if null
102
- */
103
- getHeight(node: UserNode | null): number;
104
- /**
105
- * Calculates the balance factor of a node.
106
- *
107
- * @param N - The node to calculate the balance factor for
108
- * @returns The balance factor (difference between left and right heights)
109
- */
110
- getBalanceFactor(N: UserNode | null): number;
111
- /**
112
- * Retrieves a node from the tree by its composite key.
113
- *
114
- * @param id - The composite key string to search for
115
- * @param node - The current node being evaluated
116
- * @returns The matching UserNode if found, null otherwise
117
- */
118
- getFromNode(id: string, node: UserNode | null): UserNode | null;
119
- /**
120
- * Removes a node from the tree by its composite key.
121
- *
122
- * @param passedNode - The current node being evaluated
123
- * @param id - The composite key string to remove
124
- * @returns The root node after removal
125
- *
126
- * @remarks
127
- * Implements standard BST deletion with in-order successor replacement.
128
- */
129
- removeNode(passedNode: UserNode | null, id: string): UserNode | null;
130
- /**
131
- * Counts all nodes below and including the given node.
132
- *
133
- * @param root - The root node to start counting from
134
- * @returns The total number of nodes in the subtree
135
- *
136
- * @remarks
137
- * Recursively traverses the entire subtree to count all nodes.
138
- */
139
- countNodeBelow(root: UserNode | null): number;
140
- /**
141
- * Finds the in-order successor of a node.
142
- *
143
- * @param root - The node to find the successor from
144
- * @returns The in-order successor node (leftmost node in right subtree)
145
- *
146
- * @remarks
147
- * Used during node deletion to find the replacement node.
148
- */
149
- inOrderSuccessor(root: UserNode): UserNode;
4
+ key: string;
5
+ value: Map<number, LConcept>;
6
+ connectionValue: Map<number, LConnection>;
7
+ constructor(key: string, value: LConcept, connectionValue: LConnection);
150
8
  }