From 4bb05b4c8c17d105547bc5e2b792af65d2baf902 Mon Sep 17 00:00:00 2001 From: Mees van der Wijk Date: Fri, 30 Jan 2026 14:07:15 +0100 Subject: [PATCH] Added more documentation --- ModuleServerAPI.md | 92 +++++++++++++---- ModuleServerAPIDatabase.md | 200 +++++++++++++++++++++++++++++++++++++ _Sidebar.md | 107 ++++++++++---------- 3 files changed, 324 insertions(+), 75 deletions(-) create mode 100644 ModuleServerAPIDatabase.md diff --git a/ModuleServerAPI.md b/ModuleServerAPI.md index 9837444..66b44c4 100644 --- a/ModuleServerAPI.md +++ b/ModuleServerAPI.md @@ -168,7 +168,7 @@ api.hasClient(clientId); Assigns an event to be triggered when a new ModuleClientAPI connects. ```javascript -api.onNewClient(callback); +api.onClientConnects(callback); ``` | Argument | Type | Description | @@ -180,7 +180,7 @@ api.onNewClient(callback); Assigns an event to be triggered when a new ModuleClientAPI disconnects. ```javascript -api.onNewClient(callback); +api.onClientDisconnects(callback); ``` | Argument | Type | Description | @@ -189,18 +189,18 @@ api.onNewClient(callback); ## Properties -### onModulePropertyUpdate +### onModulePropertyChange -Register a listener for when a module property updates. The listener will also be triggered on initial module creation and when the server starts up. +Register a listener for when a module property changes. The listener will also be triggered on initial module creation and when the server starts up. ```javascript -api.onModulePropertyUpdate(propertyId, callback); +api.onModulePropertyChange(propertyId, callback); ``` -| Argument | Type | Description | -| ---------- | ------------------ | ----------------------------------------------- | -| propertyId | string | The property ID that the listener will receive. | -| callback | ( value:any ):void | Function that receives the new property value. | +| Argument | Type | Description | +| ---------- | ------------------------------------------------------- | ----------------------------------------------- | +| propertyId | string | The property ID that the listener will receive. | +| callback | ( property:[Property](./ModuleServerAPIProperty) ):void | Function that receives the new property. | ### getModuleProperties @@ -224,7 +224,7 @@ api.getModuleProperty(propertyId); | ---------- | ------ | --------------------------------------- | | propertyId | string | The id of the property you want to get. | -**Returns** [Property](./ModuleServerAPIProperty) _Reference property_ +**Returns** [Property](./ModuleServerAPIProperty) _Module property_ ### hasModuleProperty @@ -240,18 +240,18 @@ api.hasModuleProperty(propertyId); **Returns** boolean _Has module property_ -### onReferencePropertyUpdate +### onReferencePropertyChange -Register a listener for when a reference property updates in a scene change. +Register a listener for when a reference property changes. ```javascript -api.onReferencePropertyUpdate(propertyId, callback); +api.onReferencePropertyChange(propertyId, callback); ``` -| Argument | Type | Description | -| ---------- | ------------------ | ----------------------------------------------- | -| propertyId | string | The property ID that the listener will receive. | -| callback | ( value:any ):void | Function that receives the new property value. | +| Argument | Type | Description | +| ---------- | ----------------------------------------------------------------------- | ----------------------------------------------- | +| propertyId | string | The property ID that the listener will receive. | +| callback | ( sceneId:string, property:[Property](./ModuleServerAPIProperty) ):void | Function that receives the new property. | ### getReferenceProperties @@ -338,6 +338,14 @@ api.getChannelModules(); ### hasChannelModules +Check if a module exists within the channel. + +```javascript +api.hasChannelModules(); +``` + +**Returns** boolean _Module exists_ + ## Cues ### finishServerCondition @@ -487,6 +495,8 @@ api.readJSON(scope, filename, callback); | filename | string | The name of the file. | | callback | ( json:any ):void | Function will be called with the JSON once it's loaded. | +**Returns** Promise\ _Loaded JSON data_ + ### writeJSON Write a file as JSON. @@ -502,6 +512,24 @@ api.writeJSON(scope, filename, json, callback?); | json | object | The JSON data to write. | | (Optional) callback | function | Function will be called with the JSON was saved. | +**Returns** Promise\ _Write successful_ + +### readFile + +Read a file. + +```javascript +api.readJSON(scope, filename, callback); +``` + +| Argument | Type | Description | +| -------- | --------------------------------------------- | ------------------------------------------------------- | +| scope | 'static' \| 'module' \| 'channel' \| 'static' | The scope of the file. | +| filename | string | The name of the file. | +| callback | ( json:any ):void | Function will be called with the JSON once it's loaded. | + +**Returns** Promise\ _Loaded data_ + ### writeFile Write a file. @@ -518,6 +546,8 @@ api.writeFile(scope, filename, data, options, callback?); | options | Object \| string | Writing options/mode to use. See [fs.writeFile](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback). | | (Optional) callback | function | Function will be called with the JSON was saved. | +**Returns** Promise\ _Write successful_ + ### fileExists Check if a file exists. @@ -526,11 +556,29 @@ Check if a file exists. api.fileExists(scope, filename, callback); ``` -| Argument | Type | Description | -| -------- | --------------------------------------------- | ---------------------------------------------------------------- | -| scope | 'static' \| 'module' \| 'channel' \| 'static' | The scope of the file. | -| filename | string | The name of the file. | -| callback | ( exists:boolean ):void | Function will be called when the file exists check has finished. | +| Argument | Type | Description | +| ------------------- | --------------------------------------------- | ---------------------------------------------------------------- | +| scope | 'static' \| 'module' \| 'channel' \| 'static' | The scope of the file. | +| filename | string | The name of the file. | +| (Optional) callback | ( exists:boolean ):void | Function will be called when the file exists check has finished. | + +**Return** Promise\ _File exists_ + +### loadDatabase + +Load a database into memory. Will create a new one if it does not exist yet. + +```javascript +api.loadDatabase(scope, filename, specification); +``` + +| Argument | Type | Description | +| ------------- | ------------------------------------------------------------------------- | ------------------------------ | +| scope | 'module' \| 'channel' \| 'static' | The scope of the file. | +| filename | string | The name of the file. | +| specification | [DatabaseSpecification](./ModuleServerAPIDatabase#database-specification) | Specification of the database. | + +**Return** [Database](./ModuleServerAPIDatabase#) _Database instance_ ### addHost diff --git a/ModuleServerAPIDatabase.md b/ModuleServerAPIDatabase.md new file mode 100644 index 0000000..b028c76 --- /dev/null +++ b/ModuleServerAPIDatabase.md @@ -0,0 +1,200 @@ +# ModuleServerAPI Database + +The ModuleServerAPI allows loading sqlite3 database into memory using it's own wrapper. + +## Database Specification + +To load a database, execute the [api.loadDatabase](./ModuleServerAPI#loaddatabase) with the file location and a database specification. This specification tells the database handler which tables should exist with what columns. This specification is automatically parsed on load. New tables or columns will automatically be added and removed entries from the specification will also be removed from the database. The possible column types are `NULL`, `TEXT`, `INTEGER`, `REAL`, `BLOB`. For storing JSON objects use the `TEXT` type and for boolean use `INTEGER`. Below is an example of a database specification. + +```JSON +{ + "tableName": { + "columnName": { + "type": "TEXT", + "primary": true + }, + "anotherColumnName": { + "type": "INTEGER" + } + }, + "anotherTable": { + "columnName": { + "type": "TEXT", + "primary": true + }, + "blobColumn": { + "type": "BLOB" + }, + "readColumn": { + "type": "REAL" + } + } +} +``` + +## Database Instance + +This is the class respresenting the entire database. + +### close + +Close the database. + +```javascript +database.close(); +``` + +### getTable + +Get a table within the database. + +```javascript +database.getTable(tableId); +``` + +| Argument | Type | Description | +| -------- | ------ | -------------------- | +| tableId | string | The ID of the table. | + +**Return** [DatabaseTable](./ModuleServerAPIDatabase#databasetable-instance) _DatabaseTable instance_ + +### run + +Run a raw sql query on the database. + +```javascript +database.run(query, amps?:string[]); +``` + +| Argument | Type | Description | +| --------------- | -------- | ---------------------------------------------------- | +| query | string | The SQL query to run. | +| (Optional) amps | string[] | Safely include parameters to prevent SQL injections. | + +**Returns** any[] _Returns from the query_ + +### fetchColumnsForTable + +Fetch the column ids of a table. + +| Argument | Type | Description | +| -------- | ------ | ----------------------------------- | +| table | string | The table to fetch the column from. | + +## DatabaseTable Instance + +Class respresenting a table within the database. + +### getAllRows + +Get all rows in the table. + +```javascript +table.getAllRows(); +``` + +**Returns** Promise\<{ [key:string]: any}[]> _All rows in the table._ + +### getPrimaryColumnValues + +Get all primary column values. + +```javascript +table.getPrimaryColumnValues(); +``` + +**Returns** Promise\ _All rows in the table._ + +### getValue + +Fetch the value of a specific cell. + +```javascript +table.getValue(primaryKeyValue, columnId); +``` + +| Argument | Type | Description | +| --------------- | ------ | --------------------------------- | +| primaryKeyValue | string | The primary key value of the row. | +| columnId | string | The id of the column. | + +**Returns** Promise\ _Value of the cell_ + +### getValueAsJSON + +Fetch the value as JSON of a specific cell. JSON objects are saved as text so make sure the column type is `TEXT`. + +```javascript +table.getValue(primaryKeyValue, columnId); +``` + +| Argument | Type | Description | +| --------------- | ------ | --------------------------------- | +| primaryKeyValue | string | The primary key value of the row. | +| columnId | string | The id of the column. | + +**Returns** Promise\ _Value of the cell as JSON._ + +### getValueAsBoolean + +Fetch the value as boolean of a specific cell. Booleans are saved a binary so make sure the column type is `INTEGER`. + +```javascript +table.getValue(primaryKeyValue, columnId); +``` + +| Argument | Type | Description | +| --------------- | ------ | --------------------------------- | +| primaryKeyValue | string | The primary key value of the row. | +| columnId | string | The id of the column. | + +**Returns** Promise\ _Value of the cell as boolean._ + +### updateRow + +Update a row in the table. + +```javascript +table.updateRow(primaryKeyValue, values); +``` + +| Argument | Type | Description | +| --------------- | ------------------------- | --------------------------------- | +| primaryKeyValue | string | The primary key value of the row. | +| values | { [columnId:string]: any} | The values to set. | + +**Returns** Promise\ _Row has been updated._ + +### removeRow + +Update a row in the table. + +```javascript +table.removeRow(primaryKeyValue); +``` + +| Argument | Type | Description | +| --------------- | ------ | --------------------------------- | +| primaryKeyValue | string | The primary key value of the row. | + +**Returns** Promise\ _Row has been removed._ + +### removeAllRows + +Remove all rows in the table. + +```javascript +table.removeAllRows(); +``` + +**Returns** Promise\ _All rows have been removed._ + +### getPrimaryKeyColumn + +Get the primary key column of the table. + +```javascript +table.getPrimaryKeyColumn(); +``` + +**Returns** string _The primary column id._ diff --git a/_Sidebar.md b/_Sidebar.md index 2908fa8..7ed956e 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -1,70 +1,71 @@ ### [Getting Started](./Home) -- [Introduction](./Home) -- [Prerequisites](./Prerequisites) -- [Setting up server](./ServerSetup) -- [Config](./Config) +- [Introduction](./Home) +- [Prerequisites](./Prerequisites) +- [Setting up server](./ServerSetup) +- [Config](./Config) ### [Module Development](./ModuleDevelopmentIntroduction) -- [Introduction](./ModuleDevelopmentIntroduction) -- [V2 Module Structure](./V2ModuleStructure) - - [module.ts](./ModuleTS) -- [V1 Module Structure](./V1ModuleStructure) - - [module.json](./ModuleJSON) -- [Development environment/Building](./ModuleEnvironment) -- Module Config - - [Property](./ModuleConfigProperty) - - [Trigger](./ModuleConfigTrigger) - - [Condition](./ModuleConfigCondition) -- [Module Debugging](./ModuleDebugging) -- [GetiyoModuleTool](./GetiyoModuleTool) - - [ModuleStore](./ModuleStore) -- [Bug/Feature Reporting](./Reporting) -- [Contact Details](./ContactDetails) +- [Introduction](./ModuleDevelopmentIntroduction) +- [V2 Module Structure](./V2ModuleStructure) + - [module.ts](./ModuleTS) +- [V1 Module Structure](./V1ModuleStructure) + - [module.json](./ModuleJSON) +- [Development environment/Building](./ModuleEnvironment) +- Module Config + - [Property](./ModuleConfigProperty) + - [Trigger](./ModuleConfigTrigger) + - [Condition](./ModuleConfigCondition) +- [Module Debugging](./ModuleDebugging) +- [GetiyoModuleTool](./GetiyoModuleTool) + - [ModuleStore](./ModuleStore) +- [Bug/Feature Reporting](./Reporting) +- [Contact Details](./ContactDetails) ### [ModuleServerAPI](./ModuleServerAPIIntroduction) -- [Introduction](./ModuleServerAPIIntroduction) -- [ModuleServerAPI](./ModuleServerAPI) - - [Client](./ModuleServerAPIClient) - - [Property](./ModuleServerAPIProperty) - - [Important Principals](./ModuleServerAPIPrincipals) - - [Libs](./ModuleServerAPILibs) - - [LibWebSocket](./ModuleServerAPILibsWebSocketLib) - - [Communication Standard](./WebSocketLibCommuncationStandard) - - [Axios](https://axios-http.com/docs/instance) +- [Introduction](./ModuleServerAPIIntroduction) +- [ModuleServerAPI](./ModuleServerAPI) + - [Database](./ModuleServerAPIDatabase) + - [Client](./ModuleServerAPIClient) + - [Property](./ModuleServerAPIProperty) + - [Important Principals](./ModuleServerAPIPrincipals) + - [Libs](./ModuleServerAPILibs) + - [LibWebSocket](./ModuleServerAPILibsWebSocketLib) + - [Communication Standard](./WebSocketLibCommuncationStandard) + - [Axios](https://axios-http.com/docs/instance) ### [ModuleServerAPI GameLib](./ModuleServerAPIGameLibIntroduction) -- [Introduction](./ModuleServerAPIGameLibIntroduction) -- [GameLib](./ModuleServerAPIGameLib) - - [Room](./ModuleServerAPIGameLibRoom) - - [Game](./ModuleServerAPIGameLibGame) - - [GamePlayer](./ModuleServerAPIGameLibGamePlayer) - - [Scoreboard](./ModuleServerAPIGameLibScoreboard) - - [Details](./ModuleServerAPIGameLibScoreboardDetails) - - [State](./ModuleServerAPIGameLibScoreboardState) - - [GameLib CollisionSpace](./ModuleServerAPIGameLibCollisionSpace) +- [Introduction](./ModuleServerAPIGameLibIntroduction) +- [GameLib](./ModuleServerAPIGameLib) + - [Room](./ModuleServerAPIGameLibRoom) + - [Game](./ModuleServerAPIGameLibGame) + - [GamePlayer](./ModuleServerAPIGameLibGamePlayer) + - [Scoreboard](./ModuleServerAPIGameLibScoreboard) + - [Details](./ModuleServerAPIGameLibScoreboardDetails) + - [State](./ModuleServerAPIGameLibScoreboardState) + - [GameLib CollisionSpace](./ModuleServerAPIGameLibCollisionSpace) ### [ModuleClientAPI](./ModuleClientAPIIntroduction) -- [Introduction](./ModuleClientAPIIntroduction) -- [ModuleClientAPI](./ModuleClientAPI) - - [User](./ModuleClientAPIUser) - - [Property](./ModuleClientAPIProperty) - - [Neighbor](./ModuleClientAPINeighbor) - - [Neighbor Results](./ModuleClientAPINeighborResults) - - [GameLib](./ModuleClientAPIGameLib) - - [Controller](./ModuleClientAPIGameLibController) - - [Important Principals](./ModuleClientAPIPrincipals) +- [Introduction](./ModuleClientAPIIntroduction) +- [ModuleClientAPI](./ModuleClientAPI) + - [User](./ModuleClientAPIUser) + - [Property](./ModuleClientAPIProperty) + - [Neighbor](./ModuleClientAPINeighbor) + - [Neighbor Results](./ModuleClientAPINeighborResults) + - [GameLib](./ModuleClientAPIGameLib) + - [Controller](./ModuleClientAPIGameLibController) + - [Important Principals](./ModuleClientAPIPrincipals) ### ModuleApi Shared -- [RuntimeStorage](./ModuleApiGameLibRuntimeStorage) -- Gamelib - - [GameLib GameDetails](./ModuleApiGameLibGameDetails) - - [GameLib EndScreen](./ModuleAPIGameLibEndScreen) - - [GameLib TimeSpan](./ModuleApiGameLibTimeSpan) - - [GameLib FrameCycle](./ModuleApiGameLibFrameCycle) - - [GameLib Ratio](./ModuleAPIGameLibRatio) +- [RuntimeStorage](./ModuleApiGameLibRuntimeStorage) +- Gamelib + - [GameLib GameDetails](./ModuleApiGameLibGameDetails) + - [GameLib EndScreen](./ModuleAPIGameLibEndScreen) + - [GameLib TimeSpan](./ModuleApiGameLibTimeSpan) + - [GameLib FrameCycle](./ModuleApiGameLibFrameCycle) + - [GameLib Ratio](./ModuleAPIGameLibRatio)