@twin.org/core 0.0.2-next.9 → 0.0.2

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

@@ -10,7 +10,7 @@ Class to handle errors which are triggered by data already existing.
 
 ### Constructor
 
-> **new AlreadyExistsError**(`source`, `message`, `existingId?`, `cause?`): `AlreadyExistsError`
+> **new AlreadyExistsError**(`source`, `message`, `existingId?`, `properties?`, `cause?`): `AlreadyExistsError`
 
 Create a new instance of AlreadyExistsError.
 
@@ -26,7 +26,7 @@ The source of the error.
 
 `string`
 
-The message as a code.
+The message as an i18n key.
 
 ##### existingId?
 
@@ -34,6 +34,10 @@ The message as a code.
 
 The id for the item.
 
+##### properties?
+
+Any additional information for the error.
+
 ##### cause?
 
 `unknown`
@@ -50,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`
 
@@ -58,9 +62,9 @@ Runtime name for the class.
 
 ***
 
-### source?
+### source? {#source}
 
-> `optional` **source**: `string`
+> `optional` **source?**: `string`
 
 The source of the error.
 
@@ -70,9 +74,9 @@ The source of the error.
 
 ***
 
-### properties?
+### properties? {#properties}
 
-> `optional` **properties**: `object`
+> `optional` **properties?**: `object`
 
 Any additional information for the error.
 
@@ -86,9 +90,9 @@ Any additional information for the error.
 
 ***
 
-### cause?
+### cause? {#cause}
 
-> `optional` **cause**: [`IError`](../interfaces/IError.md)
+> `optional` **cause?**: [`IError`](../interfaces/IError.md)
 
 The cause of the error.
 
@@ -98,7 +102,7 @@ The cause of the error.
 
 ## Methods
 
-### fromError()
+### fromError() {#fromerror}
 
 > `static` **fromError**(`err`): [`BaseError`](BaseError.md)
 
@@ -124,7 +128,7 @@ The new instance.
 
 ***
 
-### flatten()
+### flatten() {#flatten}
 
 > `static` **flatten**(`err`): [`IError`](../interfaces/IError.md)[]
 
@@ -150,9 +154,9 @@ The list of all internal errors.
 
 ***
 
-### expand()
+### expand() {#expand}
 
-> `static` **expand**(`errors`): `undefined` \| [`IError`](../interfaces/IError.md)
+> `static` **expand**(`errors`): [`IError`](../interfaces/IError.md) \| `undefined`
 
 Expand an error tree.
 
@@ -160,13 +164,13 @@ Expand an error tree.
 
 ##### errors
 
-The list of errors to expand.
+[`IError`](../interfaces/IError.md)[] \| `undefined`
 
-`undefined` | [`IError`](../interfaces/IError.md)[]
+The list of errors to expand.
 
 #### Returns
 
-`undefined` \| [`IError`](../interfaces/IError.md)
+[`IError`](../interfaces/IError.md) \| `undefined`
 
 The first level error.
 
@@ -176,7 +180,7 @@ The first level error.
 
 ***
 
-### isErrorName()
+### isErrorName() {#iserrorname}
 
 > `static` **isErrorName**(`error`, `name`): `error is BaseError`
 
@@ -192,9 +196,9 @@ The error to test.
 
 ##### name
 
-The name to check for.
+`string` \| `RegExp`
 
-`string` | `RegExp`
+The name to check for.
 
 #### Returns
 
@@ -208,7 +212,7 @@ True if the error has the name.
 
 ***
 
-### isErrorMessage()
+### isErrorMessage() {#iserrormessage}
 
 > `static` **isErrorMessage**(`error`, `message`): `error is BaseError`
 
@@ -224,9 +228,9 @@ The error to test.
 
 ##### message
 
-The message to check for.
+`string` \| `RegExp`
 
-`string` | `RegExp`
+The message to check for.
 
 #### Returns
 
@@ -240,7 +244,7 @@ True if the error has the name.
 
 ***
 
-### isErrorCode()
+### isErrorCode() {#iserrorcode}
 
 > `static` **isErrorCode**(`error`, `code`): `boolean`
 
@@ -256,9 +260,9 @@ The error to test.
 
 ##### code
 
-The code to check for.
+`string` \| `RegExp`
 
-`string` | `RegExp`
+The code to check for.
 
 #### Returns
 
@@ -272,7 +276,7 @@ True if the error has the code.
 
 ***
 
-### someErrorName()
+### someErrorName() {#someerrorname}
 
 > `static` **someErrorName**(`error`, `name`): `error is BaseError`
 
@@ -288,9 +292,9 @@ The error to test.
 
 ##### name
 
-The name to check for.
+`string` \| `RegExp`
 
-`string` | `RegExp`
+The name to check for.
 
 #### Returns
 
@@ -304,7 +308,7 @@ True if the error has the name.
 
 ***
 
-### someErrorMessage()
+### someErrorMessage() {#someerrormessage}
 
 > `static` **someErrorMessage**(`error`, `message`): `error is BaseError`
 
@@ -320,9 +324,9 @@ The error to test.
 
 ##### message
 
-The message to check for.
+`string` \| `RegExp`
 
-`string` | `RegExp`
+The message to check for.
 
 #### Returns
 
@@ -336,7 +340,7 @@ True if the error has the name.
 
 ***
 
-### someErrorClass()
+### someErrorClass() {#someerrorclass}
 
 > `static` **someErrorClass**(`error`, `cls`): `error is BaseError`
 
@@ -368,7 +372,7 @@ True if the error has the specific class.
 
 ***
 
-### someErrorCode()
+### someErrorCode() {#someerrorcode}
 
 > `static` **someErrorCode**(`error`, `code`): `error is BaseError`
 
@@ -384,9 +388,9 @@ The error to test.
 
 ##### code
 
-The code to check for.
+`string` \| `RegExp`
 
-`string` | `RegExp`
+The code to check for.
 
 #### Returns
 
@@ -400,7 +404,7 @@ True if the error has the name.
 
 ***
 
-### isEmpty()
+### isEmpty() {#isempty}
 
 > `static` **isEmpty**(`err`): `boolean`
 
@@ -426,7 +430,7 @@ True if the error is empty.
 
 ***
 
-### isAggregateError()
+### isAggregateError() {#isaggregateerror}
 
 > `static` **isAggregateError**(`err`): `err is AggregateError`
 
@@ -452,7 +456,7 @@ True if the error is an aggregate error.
 
 ***
 
-### fromAggregate()
+### fromAggregate() {#fromaggregate}
 
 > `static` **fromAggregate**(`err`, `includeStackTrace?`): [`IError`](../interfaces/IError.md)[]
 
@@ -484,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,62 +42,28 @@ True if both arrays are empty of have the same values.
 
 ***
 
-### fromObjectOrArray()
+### fromObjectOrArray() {#fromobjectorarray}
 
-Convert an object or array to an array.
-
-#### Param
-
-The object or array to convert.
-
-#### Call Signature
-
-> `static` **fromObjectOrArray**\<`T`\>(`value`): `undefined`
+> `static` **fromObjectOrArray**\<`T`\>(`value`): `T` *extends* `undefined` ? `undefined` : `T`[]
 
 Convert an object or array to an array.
 
-##### Type Parameters
+#### Type Parameters
 
-###### T
+##### T
 
 `T` = `unknown`
 
-##### Parameters
-
-###### value
-
-`undefined`
-
-The object or array to convert.
-
-##### Returns
-
-`undefined`
-
-The array.
-
-#### Call Signature
-
-> `static` **fromObjectOrArray**\<`T`\>(`value`): `T`[]
-
-Convert an object or array to an array.
-
-##### Type Parameters
-
-###### T
-
-`T` = `unknown`
-
-##### Parameters
+#### Parameters
 
-###### value
+##### value
 
-[`ObjectOrArray`](../type-aliases/ObjectOrArray.md)\<`T`\>
+`T` \| `T`[] \| `undefined`
 
 The object or array to convert.
 
-##### Returns
+#### Returns
 
-`T`[]
+`T` *extends* `undefined` ? `undefined` : `T`[]
 
 The array.