Add script to automatically generate a declaration file for the JS API #34
Conversation
|
This PR should include adding the description of how to run the script to some type of readme. We could for example add a readme to the scripts folder |
…et wrappers, update python script
| @@ -0,0 +1 @@ | |||
| openspace_api==0.1.2 | |||
There was a problem hiding this comment.
I think this one should include the other dependencies as well? Not sure though. Haven't worked a lot with requirements files
import asyncio
import re
import shutil
There was a problem hiding this comment.
iirc these are all part of python out-of-the-box
There was a problem hiding this comment.
Yea, they are all build-in
|
|
||
| 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 |
There was a problem hiding this comment.
| # Usage | |
| # Usage in Typescript projects |
Otherwise it could be "how to use the script"
| - As of 2025-03-05 the functions `propertyValue` and `setPropertyValueSingle` do not retrieve their correct function signatures from OpenSpace due to their implementation in C++. To call these functions correctly from a TypeScript context, their type definitions must be manually adjusted: | ||
| - Change: | ||
|
|
||
| ```javascript | ||
| propertyValue: () => Promise<void> | ||
| ``` | ||
|
|
||
| - To | ||
|
|
||
| ```javascript | ||
| propertyValue: (uri: string) => Promise<unknown> | ||
| ``` | ||
|
|
||
| - Change: | ||
|
|
||
| ```javascript | ||
| setPropertyValueSingle: () => Promise<void> | ||
| ``` | ||
|
|
||
| - To: | ||
|
|
||
| ```javascript | ||
| setPropertyValuesingle: (uri: string, value: any, duration?: number, easingFunction?: string, script?: string) => Promise<void> | ||
| ``` |
There was a problem hiding this comment.
| - As of 2025-03-05 the functions `propertyValue` and `setPropertyValueSingle` do not retrieve their correct function signatures from OpenSpace due to their implementation in C++. To call these functions correctly from a TypeScript context, their type definitions must be manually adjusted: | |
| - Change: | |
| ```javascript | |
| propertyValue: () => Promise<void> | |
| ``` | |
| - To | |
| ```javascript | |
| propertyValue: (uri: string) => Promise<unknown> | |
| ``` | |
| - Change: | |
| ```javascript | |
| setPropertyValueSingle: () => Promise<void> | |
| ``` | |
| - To: | |
| ```javascript | |
| setPropertyValuesingle: (uri: string, value: any, duration?: number, easingFunction?: string, script?: string) => Promise<void> | |
| ``` |
No longer the case
| StaticFileName = "openspace-api-static.txt" | ||
| outFileName = "../declaration/openspace-api-js.d.ts" | ||
|
|
||
| def writeFunctionDocumentation(file, fun): |
There was a problem hiding this comment.
Seem we have settled on a C++ -> 4 whitespace indentation, everything else -> 2 whitespace indentation. Would think that we can apply that here as well?
| Writes a function with corresponding documentation, arguments, and return type to file | ||
| """ | ||
| writeFunctionDocumentation(file, fun) | ||
| file.write(f' {fun["name"]}: ') |
There was a problem hiding this comment.
This is only allowed in Python 3.12 and forward. https://peps.python.org/pep-0701/
I think that is fine, but say 3.8 in the readme
| file.write("type integer = number;\n") | ||
| file.write("type vec2 = [number, number];\n") | ||
| file.write("type vec3 = [number, number, number];\n") | ||
| file.write("type mat3x3 = { 1: number; 2: number; 3: number; 4: number; 5: number;" + |
There was a problem hiding this comment.
What about mat2x2 and mat4x4?
| * * | ||
| * OpenSpace-api-js * | ||
| * * | ||
| * Copyright (c) 2024-2024 * |
There was a problem hiding this comment.
| * Copyright (c) 2024-2024 * | |
| * Copyright (c) 2024-2025 * |
| @@ -0,0 +1 @@ | |||
| openspace_api==0.1.2 | |||
There was a problem hiding this comment.
Yea, they are all build-in
This PR adds a Python script to automatically generate a declaration file (.d.ts) for the JavaScript API. This give TypeScript syntax highlighting and intellisense for the entire API including the OpenSpace lua functions.
For now we keep the
openspace-ai-js.d.tsfile in this repository since it seems to be quite a process to add it to the npm @types and DefinitelyTyped repo since our Lua API is updated quite often, it will be nice to have more control over it.Usage
Simply copy the
openspace-api-js.d.tsfile from the declaration folder to the src project folder, might have to update thecompilerOptionsto include the new file as well.Generate an updated version
Run the Python script
generatetypescriptfile.pyfrom the root folder ofopenspace-api-js, while OpenSpace is running