Kalm

The Socket Optimizer

A UDP transport for the Kalm framework.

• Use fire-and-forget type messaging with the conveinience of stateful interfaces
• Supports ipv4 and ipv6 addresses
• Adds timeouts for recycling instances

Installing

npm install @kalm/udp

Options

{
    /** The udp socket family (default: udp4) */
    type?: 'udp4' | 'udp6'
    /** The ip address that shows up when calling `local()` (default: '0.0.0.0') */
    localAddr?: string
    /** UDP reuse Address seting (default: false) */
    reuseAddr?: boolean
    /** The maximum idle time for the connection before it hangs up (default: 30000) */
    socketTimeout?: number
}

For more info, refer to the Kalm Homepage

Contribute

If you think of something that you want, open an issue or file a pull request, we'll be more than happy to take a look!

License

Apache 2.0 (c) 2025 Frederic Charette

Changelog

[v8.1.1] - 2025-10-28

commit #

Minor changes (QOL)

• added warning on misnamed config parameters
• added a client disconnect() method that is an alias for destroy()
• added a secure property on ws transport config for simpler wss
• throws an error on channel subscription with non-function handler

[v8.1.0] - 2025-10-27

commit #

Minor changes

• Allowing socket objects to be passed to the Client constructor, enabling compatibility with other socket libraries.

[v8.0.1] - 2025-08-08

commit b5569f2

Bug fixes

• No longer sending empty payloads, which was problematic with the tick routine. Frame Ids are still counted as if it were sent.
• Cleanup of typescript definitions

[v8.0.0] - 2025-07-30

commit f8816cc

Breaking changes

• Updated bundling for greater compatibility (exports may behave differently)
• Deprecated the WebRTC Transport (too convoluted to fit the Kalm model)
• Changed the signature of the frame event handler from (frame: RawFrame, payloadBytes: number) to ({ body: RawFrame, payloadBytes: number}) to ensure all event handlers only have one arguments.

Minor changes

• Added support for the new native WS APIs in Node 22 and later
• Removed yarn from the toolchain. There's no reason to keep it now that NPM workspaces are more mature.
• Deprecated the agent property for the WS Transport
• Migrated the underlying Node EventEmitter to the cross-platform EventTarget system. A translation layer should keep end-user code intact.
• Fixed server connections not getting cleaned up
• Removed empty channels from frame payloads, saving bandwidth
• Changed the subscribe handler's second argument name from frame to context, to reduce confusion with its nested frame property.
• Fixed missing UDP client connect event.
• Removed the potentially misleading argument in the connect event since it only exposes the unbound socket.
• Bumped engines requirement to Node 20.x

[v7.0.0] - 2023-03-17

commit 99a3ab9

Major changes

• Standardized parameter names and expected behavior
  • Removed secure WS option, instead checking if cert and key are set
  • Routines.dynamic option hz is now maxInterval and is measured in milliseconds
  • Renamed provider internally to server for easier understanding
  • Removed previously deprecated UDP connectTimeout option
• Added UDP idle timeout behavior
• Added WS idle timeout behavior
• Added WS Agent option for proxying
• frameId counter now goes up to 0xffffffff before cycling instead of 0xffff

Bug fixes

• Fixed an issue in Routines.tick where all queues shared the same frameId counter
• Routines.tick option seed now correctly sets the frameId and starts the counter to match the expected pace
• Fixed references to Node modules in TS definitions

[v6.1.0] - 2022-09-21

commit a0e88e3

Major changes

• Removed SYN/ACK UDP handshake, which removes the socket timeout behaviour for that transport
• Added error event for UDP packet over the safe limit (16384 bytes), previous behaviour was to crash silently
• Routines are no longer event emitters, but have a size function

[v6.0.0] - 2021-04-26

commit: 47b810d

Breaking changes

• Client.remote is now a const instead of a function (breaking change)
• Client.local is now a const instead of a function (breaking change)
• Engines config in package.json now only allows node >=14

Added

• Client reference in subscribe callback is now fully featured instead of a shallow config object.
• Bumped ws version
• Added integration tests

Bug fixes

• Fixed importing when using typescript (breaking change)
• Fixed socket remote info
• Fixed multiple types, including opening port value to be a string

[v5.0.0] - 2020-06-23

commit: #

Breaking changes

• Changed default packet framing to be a pure json object
• Removed custom framing
• Added packet message cap
• Fixed multiplexing

Added

• Added more error messages
• Added tests for transport packages
• Added CHANGELOG and LICENSE to all packages

[v4.0.0] - 2020-03-28

commit: 731491d

Added

• Added more error messages
• Added tests for transport packages
• Added CHANGELOG and LICENSE to all packages
• Added 'framing' option to set packet framing to be a pure json object

[v3.3.0] - 2020-01-30

commit: af46059

Added

• Added webrtc package and examples
• Added the getChannels method on Client

Removed

• Removed home implementation of EventEmitter in favor of Node's

[v3.2.3] - 2020-01-14

commit: c188225

Added

• Added pre-hook for lint on commit

Changed

• Cleaned up Types management and typings file accessibility
• Migrated test suite to Jest and centralized test tooling
• Removed output rollup, and using only tsc with none modules
• Fixed linting (was not targeting .ts files properly)
• Fixed stats events (were previously unreachable, now exposed through client emitter as .*)
• Fixed timeout behavior (only logged, now actually disconnects)

[v3.1.2] - 2019-07-01

commit: fac8047

Changed

• Changed dev tooling from lerna to yarn workspaces
• Changed dev tooling from tslint to eslint + @typescript-eslint
• Housekeeping

[v3.0.0] - 2019-01-18

commit: a4c687d

Added

• New monorepo structure
• Massive new changes to the interface

Changed

• Serialization is now a toggle for json/binary
• Re-written the entire codebase in Typescript

Removed

• Transports are no longer bundled and must be installed separately and must be instantiated with options.
  • ipc
  • tcp
  • udp
  • ws
• Profiles become routines and must be instantiated with options.
• No more session stores
• No more encryption

[v2.6.1] - 2018-01-27

commit: 7393d17

Added

• Added package-lock.json file
• Added server reference in the client object

[v2.5.0] - 2017-09-21

commit: 2c687f6

Added

• Added engines reqs

Changed

• Some minor performance tuning

[v2.4.0] - 2017-09-01

commit: a7b8f95

Changed

• Tuned performances
• Added build targets for Node 8.x and 6.x
• UDP client cache (tied with socketTimeout)
• Bumped dependencies
• Proper callback on disconnect

Removed

• Dropped support for Node 4.x

[v2.3.0] - 2017-07-25

commit: f323bcd

Added

• Added realtime profile
• Added JSDoc
• Added parameter validation and error messages

Changed

• Better performances (3x with default congestion)

[v2.2.0] - 2017-06-21

commit: b9f3bdd

Added

• Added support for node 8

[v2.1.0] - 2017-06-20

commit: 129146f

Changed

• Simplified and optimized queue system logic
• Now allowing 0 to be passed as tick value in profiles
• Added warning when non-serialized message are sent and serial config is null
• Fixed hanging packets on maxBytes just reached

[v2.0.0] - 2017-03-02

commit: b5209ec

Added

• Migrated the codebase from the original repo
• Implemeted new interface