@apple/cktool.core

CKTool JS Core Package

This package is part of the CKTool JS JavaScript client library suite and is used to support CKTool JS client libraries.

This package defines the Configuration class that must be instantiated in order to invoke API operations.

Each API operation is exposed with a function that returns a CancellablePromise with the results of the operation.

Strict Numeric Types

There are several branded types used to mark validated values. For example, the Int32 type is a branded numeric type that is assignaable to number but number is not directly assignable to it.

const a: number = toInt32(12); // OK
const b: Int32 = 12; // Error

Casting Functions

This client library attempts to be as type-safe as possible. There are several data types that must be validated in order to be passed to an operation. For example, where an Int32 would be expected, you must first pass your constant through the toInt32 cast function. The Int32 cast function does the following:

• Validates that the value is a numeric type.
• Validates that the number is an integer in Int32 range.
• Returns an Int32 value that will pass type checking.

Do NOT use type assertions to cast a related type, such as number to a branded type. Such an approach is not guaranteed to compile in future and an invalid value may be type asserted, which can lead to errors down the line.

Int64, Float, and Double Support

Support for Int64, Float, and Double is achieved with the bignumber.js library. Whenever one of those numeric types are returned from an operation, it will be a BigNumber instance. In order to perform operations on those instances, such as addition or subtraction, you'll need to use the BigNumber methods. See the documentation for BigNumber at https://github.com/MikeMcl/bignumber.js.

The toInt64 cast function will do the following:

• Validates that the value is a numeric type.
• Validates that the number is an integer in Int64 range.
• Returns a BigNumber instance of type Int64.

The toFloat cast function will do the following:

• Validates that the value is a numeric type.
• Validates that the number is an integer in Float range.
• Returns a BigNumber instance of type Float.

The toDouble cast function will do the following:

• Validates that the value is a numeric type.
• Validates that the number is an integer in Double range.
• Returns a BigNumber instance of type Double.

UUIDs

To pass a Uuid to a function, use the toUuid cast function. To create a Uuid object, use the createUuid function.