add typescript definitions

This commit is contained in:
Simon Laux 2022-01-17 23:49:35 +01:00 committed by B. Petersen
parent 0ef2d20775
commit 19f628ec50
No known key found for this signature in database
GPG key ID: 3B88E92DEA8E9AFC
5 changed files with 110 additions and 3 deletions

23
.github/workflows/simulator_types.yml vendored Normal file
View file

@ -0,0 +1,23 @@
name: Are types and sim in sync?
on:
push:
branches: [master]
pull_request:
branches: [master]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Use Node.js 14.x
uses: actions/setup-node@v1
with:
node-version: 14.x
- name: install typescript
run: |
npm i -g typescript
- name: check if simulator (webxdc.js) and types (webxdc.d.ts) are in sync
run: |
tsc --noEmit --allowJs webxdc.js

View file

@ -21,3 +21,21 @@ and send it to your friends :)
note, that the api is not yet complete,
this is just a, maybe already useful, proof-of-concept for now.
## use type-checking and completion
If you are using vscode you can have autocompletion and type-checking even without using typescript.
just add these two lines to your javascript source files:
```js
//@ts-check
/** @typedef {import('./webxdc').WEBxDC} WEBxDC */
```
Without vscode you need to install typescript and then run the check manually.
```sh
npm -g typescript
tsc --noEmit --allowJs webxdc.js # to check if types and simulator are in sync
tsc --noEmit --allowJs your_js_file.js
```

View file

@ -14,7 +14,7 @@ case "$1" in
esac
rm "$PACKAGE_NAME.xdc" 2> /dev/null
zip -9 --recurse-paths "$PACKAGE_NAME.xdc" * --exclude README.md webxdc.js "*.sh" "*.xdc"
zip -9 --recurse-paths "$PACKAGE_NAME.xdc" * --exclude README.md webxdc.js webxdc.d.ts "*.sh" "*.xdc"
echo "success, archive contents:"
unzip -l "$PACKAGE_NAME.xdc"

64
webxdc.d.ts vendored Normal file
View file

@ -0,0 +1,64 @@
//@ts-check
type SendingStateUpdate<T> = {
/** the payload, deserialized json:
* any javascript primitive, array or object. */
payload: T;
/** optional, short, informational message that will be added to the chat,
* eg. "Alice voted" or "Bob scored 123 in MyGame";
* usually only one line of text is shown,
* use this option sparingly to not spam the chat. */
info?: string;
/** optional, short text, shown beside app icon;
* it is recommended to use some aggregated value,
* eg. "8 votes", "Highscore: 123" */
summary?: string;
};
type RecievedStateUpdate<T> = {
/** the payload, deserialized json */
payload: T;
};
interface WEBxDC<T> {
/** Returns the peer's own address.
* This is esp. useful if you want to differ between different peers - just send the address along with the payload,
* and, if needed, compare the payload addresses against selfAddr() later on. */
selfAddr(): string;
/** Returns the peer's own name. This is name chosen by the user in their settings, if there is nothing set, that defaults to the peer's address. */
selfName(): string;
/**
* set a listener for new state updates
* note that own state updates, that you send with {@link sendStateUpdate}, also trigger this method
* */
setUpdateListener(cb: (stateUpdate: RecievedStateUpdate<T>) => void): void;
/**
* In case your Webxdc was just started,
* you may want to reconstruct the state from the last run - and also incorporate updates that may have arrived while the app was not running.
*/
getAllUpdates(): RecievedStateUpdate<T>[];
/**
* Webxdc apps are usually shared in a chat and run independently on each peer. To get a shared state, the peers use sendUpdate() to send updates to each other.
* @param description short, human-readable description what this update is about. this is shown eg. as a fallback text in an email program.
*/
sendUpdate(update: SendingStateUpdate<T>, description: string): void;
}
////////// ANCHOR: global
declare global {
interface Window {
webxdc: WEBxDC<any>;
}
}
////////// ANCHOR_END: global
export { SendingStateUpdate, RecievedStateUpdate, WEBxDC };
/* Types for the Simulator */
declare global {
interface Window {
addXdcPeer: () => void;
clearXdcStorage: () => void;
alterXdcApp: () => void;
}
}

View file

@ -1,6 +1,8 @@
// debug friend: document.writeln(JSON.stringify(value));
//@ts-check
/** @type {import('./webxdc').WEBxDC<any>} */
window.webxdc = (() => {
var updateListener = () => {};
var updateListener = (_) => {};
var updatesKey = "__xdcUpdatesKey__";
window.addEventListener('storage', (event) => {
if (event.key == null) {
@ -52,7 +54,7 @@ window.addXdcPeer = () => {
window.open(url);
// update next peer ID
params.set("next_peer", peerId + 1);
params.set("next_peer", String(peerId + 1));
window.location.hash = "#" + params.toString();
}