diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..a4cc790 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,51 @@ +{ + "MD003": { + "style": "atx" + }, + "MD004": { + "style": "dash" + }, + "MD007": { + "indent": 2, + "start_indented": true + }, + "MD012": false, + "MD013": false, + "MD022": false, + "MD024": { + "siblings_only": true + }, + "MD029": { + "style": "one" + }, + "MD031": false, + "MD032": false, + "MD033": false, + "MD035": { + "style": "---" + }, + "MD041": { + "allow_preamble": true + }, + "MD046": { + "style": "fenced" + }, + "MD048": { + "style": "backtick" + }, + "MD049": { + "style": "asterisk" + }, + "MD050": { + "style": "asterisk" + }, + "MD051": false, + "MD055": { + "style": "leading_and_trailing" + }, + "MD058": false, + "MD059": false, + "MD060": { + "style": "compact" + } +} diff --git a/README.md b/README.md index 92f4af1..cc40875 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,129 @@ # openspace-api-js -JavaScript library to interface with [OpenSpace](https://github.com/OpenSpace/OpenSpace) using sockets and WebSockets. -## Work in progress -Both the API and libary are still very much work in progress, and are subject to change. +TypeScript/JavaScript library for interfacing with [OpenSpace](https://github.com/OpenSpace/OpenSpace) via TCP sockets and WebSockets. -## Documentation -A [reference](https://openspace.github.io/openspace-api-js) can be found here. Examples are available below: +## Installation -### NodeJS in the terminal -https://github.com/OpenSpace/openspace-api-js/blob/master/examples/example.ts provides an example of how to connect from a NodeTS. To run it run the following in a terminal: +### npm + +If you are using npm, install the latest version: + +```sh +npm install openspace-api-js +``` + +### Script tag + +If you are including the API via a script tag, the preferred approach is to load it directly from the OpenSpace CDN: + +```html + +``` + +If you require an offline-capable version, download the [latest release](https://github.com/OpenSpace/openspace-api-js/blob/master/dist/openspace-api.js) and serve it locally: + +```html + +``` + +## Migration + +If you are upgrading from a previous version of this library, please see the [migration guide](https://docs.openspaceproject.com/releases-v0.22/building-content/api/api-migration.html). + +## Usage + +The TypeScript/JavaScript API can be used in both Node.js setups as well as browser-based setups. + +### Node.js (TCP socket) + +Connects to OpenSpace on port **4681** by default. + +[TypeScript example](https://github.com/OpenSpace/openspace-api-js/blob/master/examples/example.ts) and [JavaScript example](https://github.com/OpenSpace/openspace-api-js/blob/master/examples/example.js) provide examples of how to connect from a Node.js application. To run the bundled Node.js example: ```sh npm install -npm run example +npm run examples-typescript # TypeScript +npm run examples-javascript # JavaScript ``` -### Simple website -https://github.com/OpenSpace/openspace-api-js/blob/master/examples/index.html provides an example of connecting to OpenSpace from a website. For simplicity, the example is self-contained in the index.html file. +### Browser (WebSocket) + +Connects to OpenSpace on port **4682** by default. + +If you are loading the library as a plain ` + +``` + +See [HTML example](https://github.com/OpenSpace/openspace-api-js/blob/master/examples/index.html) for a complete working example. For simplicity, it is self-contained in the index.html file. + +If you are importing the library as an ES module from an npm-based project, import the entry point directly: -### Web application -For a proper example of how to interact with OpenSpace from a web application using npm, webpack and modern ES versions, please refer to https://github.com/OpenSpace/openspace-api-web-example. +```ts +import openspaceApi from 'openspace-api-js'; + +const api = openspaceApi('localhost', 4682); +``` + +## Generating types from your OpenSpace build + +The package ships with pre-generated types targeting a specific OpenSpace version. If your build differs, you can regenerate them locally. There are two separate generators, one for topic types and one for the Lua library. Both write directly into `src/types/generated/`. + +### Topic types (`generate-topic-types`) + +Reads JSON schema files from OpenSpace's `support/types/` directory and compiles them to TypeScript using `json-schema-to-typescript`. + +**Prerequisites:** + + - Node.js + - OpenSpace version 0.22 or later + +**Steps:** + +1. Run OpenSpace `DocsWriter.exe` +1. Locate the `support/types/` directory in your OpenSpace source tree +1. Run: + +```sh +npm run generate-topic-types -- "/support/types" +``` + +This writes the generated files into `src/types/generated/` and rebuilds the `AllTopics` union type used throughout the API. + + +### Lua library types (`generate-lua-library`) + +Connects to a running OpenSpace instance, fetches the full Lua API documentation via the `documentation` topic, and generates `src/types/generated/openspacelualibrary.ts`. + +> **Why generate this instead of publishing it once?** The OpenSpace Lua API changes frequently, so these types are generated from a live instance rather than published to `@types` or DefinitelyTyped. Keeping generation in this repo means changes can be reflected immediately without going through an external approval process. + +**Prerequisites:** + + - Python >= 3.12 + - The [OpenSpace Python API](https://github.com/OpenSpace/openspace-api-python) must be installed and importable + - OpenSpace must be running and reachable on `localhost:4681` + +**Steps:** + +1. Start OpenSpace. +1. Run: + +```sh +npm run generate-lua-library +``` -### Observable Notebook -Use Obserable notebooks to interact with OpenSpace locally: -https://observablehq.com/@emiax/openspace-notebook-example -This may be useful for tinkering, GUI prototyping and testing the lua interface during development. +This installs the Python dependencies (via `pip install -r script/requirements.txt`) and runs `script/generatetypescriptfile.py`, writing the result to `src/types/generated/openspacelualibrary.ts`. -## API versioning -The Lua function types in this package are generated against a specific OpenSpace version. -If your OpenSpace version differs, the API will still work at runtime but type hints -may be inaccurate. Check the package changelog to see which OpenSpace version the -types were generated against. \ No newline at end of file +> **Note:** The generated file is specific to the OpenSpace version that was running when the script executed. Type hints may be inaccurate if your runtime version differs from the version used to generate them. diff --git a/script/README.md b/script/README.md deleted file mode 100644 index 29efaa0..0000000 --- a/script/README.md +++ /dev/null @@ -1,59 +0,0 @@ -# OpenSpace JavaScript API - TypeScript Declaration Generator - -This folder contains a helper Python script that generates a TypeScript declaration file (`d.ts`) for the OpenSpace Javascript API. This allows developers using TypeScript to have syntax highlighting, IntelliSense, and type definitions for the entire API, including OpenSpace Lua functions. - -## Why this exists - -Instead of publishing the `openspace-api-js.d.ts` file to the @types namespace on npm or the DefinitelyTyped repository, we keep it in this repository. Since the OpenSpace Lua API updates frequently, maintaining control over the TypeScript declaration file ensures that changes can be reflected quickly without going through a lengthy approval process. - -## Usage in TypeScript Projects - -1. Copy the `openspace-api-js.d.ts` file from the `declaration` folder to your project's `src` folder. -2. Ensure that your TypeScript configuration (`tsconfig.json`) includes the copied `.d.ts`file in `compilerOptions`, if necessary. - -## Generating an Updated TypeScript Declaration File - -The TypeScript declaration file needs to match the Lua API of the specific OpenSpace version you're using for your project. Note that the file in this repository might not be up to date with the latest OpenSpace master, or even released version. - -To generate an updated `openspace-api-js.d.ts` file: - -1. Start OpenSpace -2. Run the Python script using: - -```sh -npm run generate-lua-library -``` - -Alternatively: - -1. Start OpenSpace -2. Navigate to the script folder of the `openspace-api-js` repository: - -```sh -cd openspace-api-js/script -``` - -3. Install dependencies using: - -```sh -pip install -r requirements.txt -``` - -4. Run the Python Script - -```sh -python generatetypescriptfile.py -``` - -5. The updated `openspace-api-js.d.ts` file will be saved automatically in the `declaration` folder. - -## Prerequisites - -- Python >= 3.12 -- The OpenSpace Python API is required, see [repository](https://github.com/OpenSpace/openspace-api-python) for further details. -- Dependencies must be installed using the provided `requirements.txt` file. -- OpenSpace must be running when executing the script - -## Caveats - -- File Updates: Keep in mind that the TypeScript declaration file in this repository may not be updated at the same rate as the OpenSpace project itself. Therefore, you might encounter discrepancies between the API definitions here and the latest version of OpenSpace.