@twin.org/core 0.0.3-next.21 → 0.0.3-next.23

package/docs/examples.md

@@ -1 +1,308 @@
-# @twin.org/core - Examples
+# Core Examples
+
+Use these snippets to validate input, transform data and handle errors consistently in shared runtime code.
+
+## Is
+
+```typescript
+import { Is } from '@twin.org/core';
+
+console.log(Is.string('alpha')); // true
+console.log(Is.number(42)); // true
+console.log(Is.array(['a', 'b'])); // true
+console.log(Is.objectValue({ id: 'u-1' })); // true
+console.log(Is.boolean(false)); // true
+console.log(Is.json('{"ok":true}')); // true
+console.log(Is.email('dev@example.org')); // true
+console.log(Is.dateTimeString('2026-03-09T11:32:00Z')); // true
+console.log(Is.stringHex('aabbccdd')); // true
+console.log(Is.uuidV7('019531ce-6f7d-7c08-a6f3-f6f7cf9f41b0')); // true
+```
+
+## Guards
+
+```typescript
+import { Guards } from '@twin.org/core';
+import { nameof } from '@twin.org/nameof';
+
+const name = 'Ari';
+const profile = {
+  age: 31,
+  active: true
+};
+const createdAt = new Date('2026-03-09T10:00:00.000Z');
+
+Guards.stringValue(this.CLASS_NAME, nameof(name), name);
+Guards.objectValue(this.CLASS_NAME, nameof(profile), profile);
+Guards.integer(this.CLASS_NAME, nameof(profile.age), profile.age);
+Guards.boolean(this.CLASS_NAME, nameof(profile.active), profile.active);
+Guards.date(this.CLASS_NAME, nameof(createdAt), createdAt);
+
+console.log(name.toUpperCase()); // ARI
+console.log(profile.age + 1); // 32
+
+const amount = 'ten';
+
+try {
+  Guards.number(this.CLASS_NAME, nameof(amount), amount);
+} catch (error) {
+  if (error instanceof GuardError) {
+    console.log(error.message); // guard.number
+  }
+}
+```
+
+## Validation
+
+```typescript
+import type { IValidationFailure } from '@twin.org/core';
+import { Validation } from '@twin.org/core';
+
+const failures: IValidationFailure[] = [];
+
+Validation.stringValue('customer.name', 'Ari', failures, undefined, {
+  minLength: 2,
+  maxLength: 30
+});
+Validation.integer('customer.age', 31, failures, undefined, {
+  minValue: 18,
+  maxValue: 120
+});
+Validation.email('customer.email', 'customer@example.org', failures);
+
+console.log(failures.length); // 0
+```
+
+## ObjectHelper
+
+```typescript
+import { ObjectHelper } from '@twin.org/core';
+
+const source = {
+  id: 'u-01',
+  profile: {
+    givenName: 'Ari'
+  },
+  tags: ['admin']
+};
+
+ObjectHelper.propertyGet(source, 'profile.givenName'); // 'Ari'
+ObjectHelper.pick(source, ['id', 'tags']); // { id: 'u-01', tags: ['admin'] }
+ObjectHelper.clone(source).id; // 'u-01'
+```
+
+## Converter
+
+```typescript
+import { Converter } from '@twin.org/core';
+
+const bytes = Converter.utf8ToBytes('twin');
+Converter.bytesToHex(bytes); // '7477696e'
+Converter.bytesToBase64Url(bytes); // 'dHdpbg'
+```
+
+## Coerce
+
+```typescript
+import { Coerce } from '@twin.org/core';
+
+Coerce.integer('19'); // 19
+Coerce.boolean('true'); // true
+Coerce.dateTime('2026-03-09T11:32:00Z')?.toISOString(); // '2026-03-09T11:32:00.000Z'
+```
+
+## StringHelper
+
+```typescript
+import { StringHelper } from '@twin.org/core';
+
+StringHelper.kebabCase('OrderCreatedEvent'); // 'order-created-event'
+StringHelper.camelCase('order-created-event'); // 'orderCreatedEvent'
+StringHelper.words('PaymentReferenceId'); // ['Payment', 'Reference', 'Id']
+```
+
+## Error Classes
+
+```typescript
+import {
+  AlreadyExistsError,
+  BaseError,
+  ConflictError,
+  GeneralError,
+  GuardError,
+  NotFoundError,
+  NotImplementedError,
+  NotSupportedError,
+  UnauthorizedError,
+  UnprocessableError,
+  ValidationError
+} from '@twin.org/core';
+
+const base = new BaseError(this.CLASS_NAME, 'baseUnexpectedFailure', { module: 'orders' });
+new AlreadyExistsError(this.CLASS_NAME, 'alreadyExistsOrder', { orderId: 'o-1' });
+new ConflictError(this.CLASS_NAME, 'conflictVersionMismatch', { expected: 3, actual: 2 });
+new GeneralError(this.CLASS_NAME, 'generalUnexpectedFailure', { retryable: false });
+new GuardError(this.CLASS_NAME, 'guardValidationFailed', { field: 'name' });
+new NotFoundError(this.CLASS_NAME, 'notFoundOrder', { orderId: 'o-1' });
+new NotImplementedError(this.CLASS_NAME, 'notImplementedFeature', {
+  feature: 'export'
+});
+new NotSupportedError(this.CLASS_NAME, 'notSupportedFormat', { format: 'xml' });
+new UnauthorizedError(this.CLASS_NAME, 'unauthorizedInvalidToken', {
+  scope: 'orders:write'
+});
+new UnprocessableError(this.CLASS_NAME, 'unprocessableInvalidContent', { field: 'email' });
+new ValidationError(this.CLASS_NAME, 'validationInputFailed', { failures: 2 });
+base.toJsonObject().name; // 'BaseError'
+```
+
+## Factory
+
+```typescript
+import { Factory } from '@twin.org/core';
+
+interface IHasher {
+  hash(value: string): string;
+}
+
+class SimpleHasher implements IHasher {
+  public hash(value: string): string {
+    return `${value}-hash`;
+  }
+}
+
+const factory = new Factory<IHasher>('hashers');
+factory.register('simple', () => new SimpleHasher());
+
+factory.create('simple').hash('abc'); // 'abc-hash'
+```
+
+## Encoding and Compression
+
+```typescript
+import { Base32, Base58, Base64, Base64Url, Compression, HexHelper } from '@twin.org/core';
+
+const bytes = new Uint8Array([1, 2, 3, 4]);
+
+Base32.encode(bytes);
+Base58.encode(bytes);
+Base64.encode(bytes);
+Base64Url.encode(bytes);
+Compression.compress(bytes, 'gzip');
+HexHelper.addPrefix('aabbcc'); // '0xaabbcc'
+```
+
+## AsyncCache and SharedStore
+
+```typescript
+import { AsyncCache, SharedStore } from '@twin.org/core';
+
+const cache = new AsyncCache<string, number>({ expirySeconds: 30 });
+await cache.exec('invoice-1', async () => 4200); // 4200
+
+SharedStore.set('region', 'eu-west-1');
+SharedStore.get<string>('region'); // 'eu-west-1'
+```
+
+## RandomHelper and NumberHelper
+
+```typescript
+import { NumberHelper, RandomHelper } from '@twin.org/core';
+
+NumberHelper.clamp(150, 0, 100); // 100
+RandomHelper.generate(16).length; // 16
+RandomHelper.generateUuidV7(); // 'xxxxxxxx-xxxx-7xxx-xxxx-xxxxxxxxxxxx'
+```
+
+## Url, Urn and BitString
+
+```typescript
+import { BitString, Url, Urn } from '@twin.org/core';
+
+const url = Url.fromParts({
+  scheme: 'https',
+  host: 'example.org',
+  pathname: '/products'
+});
+
+url.toString(); // 'https://example.org/products'
+Urn.fromValidString('urn:example:widget:123').namespaceMethod(); // 'example'
+
+const bits = BitString.fromBits([1, 0, 1, 1]);
+bits.getLength(); // 4
+```
+
+## JsonHelper
+
+```typescript
+import { JsonHelper } from '@twin.org/core';
+
+const left = { id: 'u-1', active: true };
+const right = { id: 'u-1', active: false };
+
+const patch = JsonHelper.diff(left, right);
+JsonHelper.patch(left, patch); // { id: 'u-1', active: false }
+```
+
+## ErrorHelper
+
+```typescript
+import { BaseError, ErrorHelper } from '@twin.org/core';
+
+const error = new BaseError(this.CLASS_NAME, 'saveFailed', { entityId: 'u-1' });
+const messages = ErrorHelper.formatErrors(error);
+
+messages[0]; // 'saveFailed'
+```
+
+## Type Utilities
+
+```typescript
+import type { ObjectOrArray, SingleOccurrenceArray } from '@twin.org/core';
+
+type IdOrIds = ObjectOrArray<string>;
+
+const singleId: IdOrIds = 'id-1';
+const manyIds: IdOrIds = ['id-1', 'id-2'];
+
+const withOneNumber: SingleOccurrenceArray<string, number> = ['alpha', 7, 'beta'];
+const numberOnly: SingleOccurrenceArray<string, number> = [7];
+
+interface IFoo {
+  foo: boolean;
+}
+
+interface IBar {
+  bar: string;
+}
+
+const mixedObjects: SingleOccurrenceArray<IFoo, IBar> = [
+  { foo: true },
+  { bar: 'marker' },
+  { foo: false }
+];
+```
+
+## Array, Uint8Array, Filename and Env Helpers
+
+```typescript
+import { ArrayHelper, EnvHelper, FilenameHelper, Uint8ArrayHelper } from '@twin.org/core';
+
+ArrayHelper.matches([1, 2, 3], [1, 2, 3]); // true
+Uint8ArrayHelper.concat(new Uint8Array([1, 2]), new Uint8Array([3, 4]));
+FilenameHelper.safeFilename('Q1 Report: Europe/West.csv'); // 'Q1-Report-Europe-West.csv'
+EnvHelper.envToJson('API_KEY=abc\nLOG_LEVEL=debug'); // { API_KEY: 'abc', LOG_LEVEL: 'debug' }
+```
+
+## I18n
+
+```typescript
+import { I18n } from '@twin.org/core';
+
+I18n.setLocale('en');
+I18n.addDictionary('en', {
+  greeting: 'Hello {name}'
+});
+
+I18n.formatMessage('greeting', { name: 'Ari' }); // 'Hello Ari'
+```

package/docs/reference/classes/AlreadyExistsError.md

@@ -54,7 +54,7 @@ The cause of the error if we have wrapped another error.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -62,7 +62,7 @@ Runtime name for the class.
 
 ***
 
-### source?
+### source? {#source}
 
 > `optional` **source**: `string`
 
@@ -74,7 +74,7 @@ The source of the error.
 
 ***
 
-### properties?
+### properties? {#properties}
 
 > `optional` **properties**: `object`
 
@@ -90,7 +90,7 @@ Any additional information for the error.
 
 ***
 
-### cause?
+### cause? {#cause}
 
 > `optional` **cause**: [`IError`](../interfaces/IError.md)
 
@@ -102,7 +102,7 @@ The cause of the error.
 
 ## Methods
 
-### fromError()
+### fromError() {#fromerror}
 
 > `static` **fromError**(`err`): [`BaseError`](BaseError.md)
 
@@ -128,7 +128,7 @@ The new instance.
 
 ***
 
-### flatten()
+### flatten() {#flatten}
 
 > `static` **flatten**(`err`): [`IError`](../interfaces/IError.md)[]
 
@@ -154,7 +154,7 @@ The list of all internal errors.
 
 ***
 
-### expand()
+### expand() {#expand}
 
 > `static` **expand**(`errors`): [`IError`](../interfaces/IError.md) \| `undefined`
 
@@ -180,7 +180,7 @@ The first level error.
 
 ***
 
-### isErrorName()
+### isErrorName() {#iserrorname}
 
 > `static` **isErrorName**(`error`, `name`): `error is BaseError`
 
@@ -212,7 +212,7 @@ True if the error has the name.
 
 ***
 
-### isErrorMessage()
+### isErrorMessage() {#iserrormessage}
 
 > `static` **isErrorMessage**(`error`, `message`): `error is BaseError`
 
@@ -244,7 +244,7 @@ True if the error has the name.
 
 ***
 
-### isErrorCode()
+### isErrorCode() {#iserrorcode}
 
 > `static` **isErrorCode**(`error`, `code`): `boolean`
 
@@ -276,7 +276,7 @@ True if the error has the code.
 
 ***
 
-### someErrorName()
+### someErrorName() {#someerrorname}
 
 > `static` **someErrorName**(`error`, `name`): `error is BaseError`
 
@@ -308,7 +308,7 @@ True if the error has the name.
 
 ***
 
-### someErrorMessage()
+### someErrorMessage() {#someerrormessage}
 
 > `static` **someErrorMessage**(`error`, `message`): `error is BaseError`
 
@@ -340,7 +340,7 @@ True if the error has the name.
 
 ***
 
-### someErrorClass()
+### someErrorClass() {#someerrorclass}
 
 > `static` **someErrorClass**(`error`, `cls`): `error is BaseError`
 
@@ -372,7 +372,7 @@ True if the error has the specific class.
 
 ***
 
-### someErrorCode()
+### someErrorCode() {#someerrorcode}
 
 > `static` **someErrorCode**(`error`, `code`): `error is BaseError`
 
@@ -404,7 +404,7 @@ True if the error has the name.
 
 ***
 
-### isEmpty()
+### isEmpty() {#isempty}
 
 > `static` **isEmpty**(`err`): `boolean`
 
@@ -430,7 +430,7 @@ True if the error is empty.
 
 ***
 
-### isAggregateError()
+### isAggregateError() {#isaggregateerror}
 
 > `static` **isAggregateError**(`err`): `err is AggregateError`
 
@@ -456,7 +456,7 @@ True if the error is an aggregate error.
 
 ***
 
-### fromAggregate()
+### fromAggregate() {#fromaggregate}
 
 > `static` **fromAggregate**(`err`, `includeStackTrace?`): [`IError`](../interfaces/IError.md)[]
 
@@ -488,7 +488,7 @@ The array of errors.
 
 ***
 
-### toJsonObject()
+### toJsonObject() {#tojsonobject}
 
 > **toJsonObject**(`includeStackTrace?`): [`IError`](../interfaces/IError.md)
 

package/docs/reference/classes/ArrayHelper.md

@@ -14,7 +14,7 @@ Class to help with arrays.
 
 ## Methods
 
-### matches()
+### matches() {#matches}
 
 > `static` **matches**(`arr1`, `arr2`): `boolean`
 
@@ -42,7 +42,7 @@ True if both arrays are empty of have the same values.
 
 ***
 
-### fromObjectOrArray()
+### fromObjectOrArray() {#fromobjectorarray}
 
 Convert an object or array to an array.
 

package/docs/reference/classes/AsyncCache.md

@@ -14,7 +14,7 @@ Cache the results from asynchronous requests.
 
 ## Methods
 
-### exec()
+### exec() {#exec}
 
 > `static` **exec**\<`T`\>(`key`, `ttlMs`, `requestMethod`, `cacheFailures?`): `Promise`\<`T`\> \| `undefined`
 
@@ -60,7 +60,7 @@ The response.
 
 ***
 
-### get()
+### get() {#get}
 
 > `static` **get**\<`T`\>(`key`): `Promise`\<`T` \| `undefined`\>
 
@@ -88,7 +88,7 @@ The item from the cache if it exists.
 
 ***
 
-### set()
+### set() {#set}
 
 > `static` **set**\<`T`\>(`key`, `value`, `ttlMs?`): `Promise`\<`void`\>
 
@@ -128,7 +128,7 @@ Nothing.
 
 ***
 
-### remove()
+### remove() {#remove}
 
 > `static` **remove**(`key`): `void`
 
@@ -148,7 +148,7 @@ The key to remove from the cache.
 
 ***
 
-### clearCache()
+### clearCache() {#clearcache}
 
 > `static` **clearCache**(`prefix?`): `void`
 
@@ -168,7 +168,7 @@ Optional prefix to clear only entries with that prefix.
 
 ***
 
-### cleanupExpired()
+### cleanupExpired() {#cleanupexpired}
 
 > `static` **cleanupExpired**(): `void`
 

package/docs/reference/classes/Base32.md

@@ -1,6 +1,6 @@
 # Class: Base32
 
-Class to help with base63 Encoding/Decoding.
+Class to help with base32 Encoding/Decoding.
 
 ## Constructors
 
@@ -14,7 +14,7 @@ Class to help with base63 Encoding/Decoding.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -22,7 +22,7 @@ Runtime name for the class.
 
 ## Methods
 
-### decode()
+### decode() {#decode}
 
 > `static` **decode**(`base32`): `Uint8Array`
 
@@ -48,7 +48,7 @@ If the input string contains a character not in the Base32 alphabet.
 
 ***
 
-### encode()
+### encode() {#encode}
 
 > `static` **encode**(`bytes`): `string`
 

package/docs/reference/classes/Base58.md

@@ -14,7 +14,7 @@ Class to help with base58 Encoding/Decoding.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -22,7 +22,7 @@ Runtime name for the class.
 
 ## Methods
 
-### decode()
+### decode() {#decode}
 
 > `static` **decode**(`base58`): `Uint8Array`
 
@@ -48,7 +48,7 @@ If the input string contains a character not in the Base58 alphabet.
 
 ***
 
-### encode()
+### encode() {#encode}
 
 > `static` **encode**(`bytes`): `string`
 

package/docs/reference/classes/Base64.md

@@ -15,7 +15,7 @@ Sourced from https://github.com/beatgammit/base64-js.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -23,7 +23,7 @@ Runtime name for the class.
 
 ## Methods
 
-### byteLength()
+### byteLength() {#bytelength}
 
 > `static` **byteLength**(`base64`): `number`
 
@@ -45,7 +45,7 @@ The byte length of the data.
 
 ***
 
-### decode()
+### decode() {#decode}
 
 > `static` **decode**(`base64`): `Uint8Array`
 
@@ -67,7 +67,7 @@ The byte array.
 
 ***
 
-### encode()
+### encode() {#encode}
 
 > `static` **encode**(`bytes`): `string`
 

package/docs/reference/classes/Base64Url.md

@@ -15,7 +15,7 @@ https://www.rfc-editor.org/rfc/rfc4648#section-5.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -23,7 +23,7 @@ Runtime name for the class.
 
 ## Methods
 
-### decode()
+### decode() {#decode}
 
 > `static` **decode**(`base64Url`): `Uint8Array`
 
@@ -45,7 +45,7 @@ The byte array.
 
 ***
 
-### encode()
+### encode() {#encode}
 
 > `static` **encode**(`bytes`): `string`