Typescript Migration

[DynamiteAndy]

Full migration of this project to typescript, here's a more detailed breakdown of these changes:

• Moves the Touchportal Client to typescript,
• Adds types for every event and request,
• Use rslib for building,
• Use vitest for testing,
• Formatted with prettier and eslint.
• Adds tests for each function (wip: currently only connect, checkForUpdate, disconnect and log)
• Bumped all dependencies to latest version excluding eslint (eslint-config-airbnb-base does not support eslint 9 yet)
• Removed dependency on require-from-app-root (is now done via passing as param)
• Added TriggerEvent(eventId: string, states?: Record<string, string>) function - https://www.touch-portal.com/api/index.php?section=communication_trigger_event
• Strongly typed the events so consumer can just do On(TouchPortalIncomingEventType.Info) or if expecting a event from the client On(TouchPortalClientEvent.Update)
• Removed the install build step (can include the dist file when publishing to npm via github actions, and can link locally by running npm link, no need to let the end user build the client)

Renames the following functions:

Was	Now
choiceUpdate(id, value)	updateChoice(id: string, value: string[])
choiceUpdateSpecific(id, value, instanceId)	updateSpecificChoice(id: string, instanceId: string, value: string[])
connectorUpdate(id, value, data, isShortId = false)	updateConnector(value: number, connectorId?: string, shortId?: string, data?: ConnectorData[])
connectorUpdateMany(connectors)	updateMultipleConnectors(connectors: { value: number; connectorId?: string; shortId?: string; data?: ConnectorData[]; }[])
sendNotification(notificationId, title, msg, optionsArray)	showNotification(notificationId: string, title: string, msg: string, options: NotificationOption[])
settingUpdate(name, value)	updateSetting(name: string, value: string)
createStateMany(states)	createMultipleStates(states: { id: string; desc: string; defaultValue: string, number , boolean; parentGroup?: string; forceUpdate?: boolean; }[])
stateUpdate(id, value)	updateState(id: string, value: string, number, boolean)
stateUpdateMany(states)	updateMultipleStates(states: { id: string; value: string, number, boolean }[])

Changes the following function parameters

Was	Now	Reason For Change
updateActionData(actionInstanceId, data)	updateActionData(data: ActionData, instanceId?: string)	The docs specify that instanceId is not required, so have made it optional https://www.touch-portal.com/api/index.php?section=communication_create_update_action_data
choiceUpdateSpecific(id, value, instanceId)	updateSpecificChoice(id: string, instanceId: string, value: string[])	Swapped the instanceId and value params around so that identifer's are first and then values
connectorUpdate(id, value, data, isShortId = false)	updateConnector(value: number, connectorId?: string, shortId?: string, data?: ConnectorData[])	The current implementation used a boolean for if a shortId should be used or not, added shortId as a parameter so it can just be passed straight though - reading the docs however it is a mandatory parameter so more changes may be required https://www.touch-portal.com/api/index.php?section=communication_create_update_connector_data, changes will also be required to support valueDecimal (at the time of opening this pr I didn't really understand the description yet)
checkForUpdate(githubUser, githubRepo, includePrerelease = false)	checkForUpdate(githubUser: string, githubRepo: string, currentVersion: string, includePrerelease: boolean = false)	Removed the dependency that imported the users package.json to get the version, seemed like extra overhead when we are already asking them to provide the username and repo when we can get this from the package.json repository

Made the following functions private:

• pair
• log (previously logIt)
• buildUpdateConnectorDataRequest (previously buildConnectorUpdate)

Still todo:

• Test all the things to ensure original/close to original functionality😁,
• Add github actions for linting and testing (If this is okay to do so?)

[mpaperno]

Hi Andy,

Wow, lot's of work here. Appreciate the effort!

All comments below are "in my humble opinion."

Overall, personally I'd just add jsdocs to the existing JS methods and call it a day. Ultimately typescript is about linting at design/build time, which proper docs also covers (at least in compatible editors or some external linter/builder). And/or generate/maintain a separate .dts type definitions file. I'm just not sure all the additional overhead of requiring TS is actually helpful (and I do have some practical experience with doing it both ways, in other projects).

Code wise, this makes some changes which are not backwards compatible. Making some methods private, for example (eg. send() is a fallback for sending arbitrary messages, for example new API messages not explicitly supported by the JS client yet, or skipping argument validation when sending any message). The new log() method breaks null logger feature. Just to name a couple things I noticed.

EDIT: Oh, and all the methods being renamed... why? Makes it definitely incompatible with all current implementations.

It is difficult to compare the actual working code since a lot of the formatting and arrangement have changed. Some changes don't maintain current code style either (which could be changed of course but ideally in a separate commit/PR).

Other unrelated changes are included, like formatting of changelog and readme. These are personal preferences, and including them here further complicates review.

Cheers,
-Max

[DynamiteAndy]

Todo's

[DynamiteAndy]

another todo

[DynamiteAndy]

Hi @mpaperno

Thank you for the feedback, and sorry for the late response getting back to you!

I've made a start to address some of your feedback 😃,

• null logger: it now wont log if null is passed in as the logCallback, (have added tests for this too! 😁)
• Changelog and Readme formatting: reverted, this was done by prettier - I'll get it added to .pretterignore,
• send and sendArray are now public again

The function renames were for readability more than anything 😅, but yeah sadly this does introduce some breaking changes with functions being renamed - and their parameters changing (either because they have reordered or more added), I'd be more than happy to write a migration guide or look at other ways to minimize this change (readd the functions, mark as deprecated and map it to the newer functions for example).

EDIT 23/07 - I've been updating the description with a breakdown of the changes to each function to help with review - it only reflects the functions which are public

Thank you very much again 😁

[DynamiteAndy]

Todo

[DynamiteAndy]

Marking as ready for review, all that is left is to add test's for each thing, but this PR is already bulky as is.

I can either:

• add tests in a separate PR,
• add tests as I address any comments then,
• add all the tests now

I'd also still like to add github actions for (either this pr or another):

• Creating, tagging and publishing releases (this pr doesn't leave it up to the client to build the dist files, should be shipped with the npm package),
• Testing and linting