@webxdc/types
v2.1.2
Published
TypeScript type definitions for webxdc
Downloads
1,293
Readme
Types for webxdc
When you develop a webxdc app, you use the webxdc API to communicate with other instances of the same webxdc application.
The API is available on window.webxdc
.
When you develop your webxdc app in TypeScript, it's handy to have proper types for this API. This library provides those types for you.
Why use this?
- you want better autocomplete in your IDE (js and ts)
- you want to see docuemntation on hover in your IDE (js and ts)
- you need types for typescript typechecking
Usage
You can install this using:
npm install -D @webxdc/types
You should have a type that describes your webxdc payload structure in use by your application:
type Payload = {
label: string;
value: number;
};
Once you have a Payload
type, you can declare the type of window.webxdc
in
your application:
import { Webxdc } from "@webxdc/types";
declare global {
interface Window {
webxdc: Webxdc<Payload>;
}
}
(write this in a file that is picked up by the typescript compiler, paths like src/types.d.ts
or src/global.d.ts
should work)
Now window.webxdc
should be fully typed.
Use this if you just want completions for the api, but not for the status update payloads, they will get the any
type with this method.
import "@webxdc/types/global";
// or
/// <reference types="@webxdc/types/global" />
Now window.webxdc
should be typed.
If your IDE supports it (vscode and it's forks do), you can add //@ts-check
to the top of your javascript file to enable typescript type checking for it.
you can then type variables like this
//@ts-check
/** @type {number} documentation of the value */
const my_var = 8;
You can use this to import the webxdc types when you need them to type your functions:
/**
* @typedef {any} MyPayload
* @typedef {import('@webxdc/types').XDCFile} XDCFile
* @typedef {import('@webxdc/types').ReceivedStatusUpdate<MyPayload>} ReceivedStatusUpdate
* @typedef {import('@webxdc/types').SendingStatusUpdate<MyPayload>} SendingStatusUpdate
* @typedef {import('@webxdc/types').Webxdc<MyPayload>} Webxdc
*/
// note that this does not set `window.webxdc` for you follow the steps below for that.
Without typed payloads
If you just want the api and not want to type your payloads you can import the types for window.webxdc
like this:
/** @typedef {import('@webxdc/types/global')} */
With typed payloads
For this you need to create a mytypes.d.ts
file declaring your payload type:
import { Webxdc } from "@webxdc/types";
// do your own payload type here
type Payload = {
label: string;
value: number;
};
declare global {
interface Window {
webxdc: Webxdc<Payload>;
}
}
Then import this file like this:
/** @typedef {import('./my_types')} */
Copy global.d.ts
and webxdc.d.ts
files into your project and use one of the methods above, adjusting the import path acordingly.
/** @typedef {import('./global')} */
/** @typedef {import('./webxdc')} */
You can also combine the two files if you have basic knowledge of typescript.