Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Better types for Scripting API #489

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Better types for Scripting API #489

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 21 additions & 21 deletions typescript/scripting-api/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,15 @@ declare namespace WoT {
* Accepts a ThingDescription and returns a ConsumedThing
* @param td thing description
*/
export function consume(td: ThingDescription): Promise<ConsumedThing>;
export function consume<T extends ThingDescription>(td: T): Promise<ConsumedThing<T>>;

/**
* Accepts an init dictionary similar to a ThingDescription.
* It returns a ExposedThing
*
* @param ptd Partial thing description
*/
export function produce(init: ExposedThingInit): Promise<ExposedThing>;
export function produce<T extends ExposedThingInit>(init: T): Promise<ExposedThing<T>>;


/**
Expand Down Expand Up @@ -104,14 +104,14 @@ declare namespace WoT {
/**
* The ConsumedThing interface instance represents a client API to operate a Thing.
*/
export interface ConsumedThing {
export interface ConsumedThing<T extends ThingDescription> {
/**
* Reads a Property value.
* Takes as arguments propertyName and optionally options.
* It returns a Promise that resolves with a Property value represented as an
* InteractionOutput object or rejects on error.
*/
readProperty(propertyName: string, options?: InteractionOptions): Promise<InteractionOutput>;
readProperty(propertyName: (keyof T["properties"]) & string, options?: InteractionOptions): Promise<InteractionOutput>;

/**
* Reads all properties of the Thing with one or multiple requests.
Expand All @@ -127,14 +127,14 @@ declare namespace WoT {
* It returns a Promise that resolves with a PropertyMap object that
* maps keys from propertyNames to values
*/
readMultipleProperties(propertyNames: string[], options?: InteractionOptions): Promise<PropertyReadMap>;
readMultipleProperties(propertyNames: ((keyof T["properties"]) & string)[], options?: InteractionOptions): Promise<PropertyReadMap>;

/**
* Writes a single Property.
* Takes as arguments propertyName, value and optionally options.
* It returns a Promise that resolves on success and rejects on failure.
*/
writeProperty(propertyName: string, value: InteractionInput, options?: InteractionOptions): Promise<void>;
writeProperty(propertyName: (keyof T["properties"]) & string, value: InteractionInput, options?: InteractionOptions): Promise<void>;

/**
* Writes a multiple Property values with one request.
Expand All @@ -150,26 +150,26 @@ declare namespace WoT {
* It returns a Promise that resolves with the result of the Action represented
* as an InteractionOutput object, or rejects with an error.
*/
invokeAction(actionName: string, params?: InteractionInput, options?: InteractionOptions): Promise<undefined | InteractionOutput>;
invokeAction(actionName: (keyof T["actions"]) & string, params?: InteractionInput, options?: InteractionOptions): Promise<undefined | InteractionOutput>;

/**
* Makes a request for Property value change notifications.
* Takes as arguments propertyName, listener and optionally options.
* It returns a Promise that resolves on success and rejects on failure.
*/
observeProperty(name: string, listener: WotListener, errorListener?: ErrorListener, options?: InteractionOptions): Promise<Subscription>;
observeProperty(name: (keyof T["properties"]) & string, listener: WotListener, errorListener?: ErrorListener, options?: InteractionOptions): Promise<Subscription>;

/**
* Makes a request for subscribing to Event notifications.
* Takes as arguments eventName, listener and optionally options.
* It returns a Promise to signal success or failure.
*/
subscribeEvent(name: string, listener: WotListener, errorListener?: ErrorListener, options?: InteractionOptions): Promise<Subscription>;
subscribeEvent(name: (keyof T["events"]) & string, listener: WotListener, errorListener?: ErrorListener, options?: InteractionOptions): Promise<Subscription>;

/**
* Returns the the object that represents the Thing Description.
*/
getThingDescription(): ThingDescription;
getThingDescription(): T;
}

export interface InteractionOptions {
Expand Down Expand Up @@ -199,7 +199,7 @@ declare namespace WoT {
/**
* The ExposedThing interface is the server API to operate the Thing that allows defining request handlers, Property, Action, and Event interactions.
**/
export interface ExposedThing {
export interface ExposedThing<T extends ExposedThingInit> {
/**
* Start serving external requests for the Thing, so that WoT Interactions using Properties, Actions and Events will be possible.
*/
Expand All @@ -216,15 +216,15 @@ declare namespace WoT {
* Throws on error.
* Returns a reference to the same object for supporting chaining.
*/
setPropertyReadHandler(name: string, handler: PropertyReadHandler): ExposedThing;
setPropertyReadHandler(name: (keyof T["properties"]) & string, handler: PropertyReadHandler): ExposedThing<T>;

/**
* Takes name as string argument and handler as argument of type PropertyWriteHandler.
* Sets the handler function for writing the specified Property matched by name.
* Throws on error.
* Returns a reference to the same object for supporting chaining.
*/
setPropertyWriteHandler(name: string, handler: PropertyWriteHandler): ExposedThing;
setPropertyWriteHandler(name: (keyof T["properties"]) & string, handler: PropertyWriteHandler): ExposedThing<T>;

/**
* Takes as arguments name and handler.
Expand All @@ -233,7 +233,7 @@ declare namespace WoT {
* Throws on error.
* Returns a reference to the same object for supporting chaining.
*/
setPropertyObserveHandler(name: string, handler: PropertyReadHandler): ExposedThing;
setPropertyObserveHandler(name: (keyof T["properties"]) & string, handler: PropertyReadHandler): ExposedThing<T>;

/**
* Takes as arguments name and handler.
Expand All @@ -242,21 +242,21 @@ declare namespace WoT {
* Throws on error.
* Returns a reference to the same object for supporting chaining.
*/
setPropertyUnobserveHandler(name: string, handler: PropertyReadHandler): ExposedThing;
setPropertyUnobserveHandler(name: (keyof T["properties"]) & string, handler: PropertyReadHandler): ExposedThing<T>;

/**
* Takes as arguments name denoting a Property name.
* Triggers emitting a notification to all observers.
*/
emitPropertyChange(name: string): void;
emitPropertyChange(name: (keyof T["properties"]) & string): void;

/**
* Takes name as string argument and handler as argument of type ActionHandler.
* Sets the handler function for the specified Action matched by name.
* Throws on error.
* Returns a reference to the same object for supporting chaining.
*/
setActionHandler(name: string, handler: ActionHandler): ExposedThing;
setActionHandler(name: (keyof T["actions"]) & string, handler: ActionHandler): ExposedThing<T>;

/**
* Takes as arguments name and handler.
Expand All @@ -265,7 +265,7 @@ declare namespace WoT {
* Throws on error.
* Returns a reference to the same object for supporting chaining.
*/
setEventSubscribeHandler(name: string, handler: EventSubscriptionHandler): ExposedThing;
setEventSubscribeHandler(name: (keyof T["events"]) & string, handler: EventSubscriptionHandler): ExposedThing<T>;

/**
* Takes as arguments name and handler.
Expand All @@ -274,18 +274,18 @@ declare namespace WoT {
* Throws on error.
* Returns a reference to the same object for supporting chaining.
*/
setEventUnsubscribeHandler(name: string, handler: EventSubscriptionHandler): ExposedThing;
setEventUnsubscribeHandler(name: (keyof T["events"]) & string, handler: EventSubscriptionHandler): ExposedThing<T>;

/**
* Takes as arguments name denoting an Event name and optionally data.
* Triggers emitting the Event with optional data.
*/
emitEvent(name: string, data?: InteractionInput): void;
emitEvent(name: (keyof T["events"]) & string, data?: InteractionInput): void;

/**
* Returns the the object that represents the Thing Description.
*/
getThingDescription(): ThingDescription;
getThingDescription(): T;
}

export type PropertyReadHandler = (options?: InteractionOptions) => Promise<InteractionInput>;
Expand Down