@twin.org/web 0.0.3-next.3 → 0.0.3-next.30

package/docs/examples.md

@@ -1 +1,108 @@
-# @twin.org/web - Examples
+# Web Examples
+
+Use these snippets for token handling, fetch utilities and HTTP header helpers in browser and server runtimes.
+
+## Jwt
+
+```typescript
+import { Jwt } from '@twin.org/web';
+
+const payload = {
+  sub: 'user-01',
+  role: 'editor'
+};
+
+const token = Jwt.encode(payload, {
+  alg: 'HS256'
+});
+
+Jwt.decode(token).sub; // 'user-01'
+```
+
+```typescript
+import { Jwt } from '@twin.org/web';
+
+const token = Jwt.encode({ sub: 'u-2' }, { alg: 'HS256' });
+Jwt.verify(token, {
+  key: 'local-signing-key'
+}); // true
+```
+
+## FetchHelper
+
+```typescript
+import { FetchHelper } from '@twin.org/web';
+
+const response = await FetchHelper.fetchJson<{ status: string }>('https://api.example.org/status', {
+  method: 'GET',
+  cacheSeconds: 30
+});
+
+response.status; // 'ok'
+```
+
+## HeaderHelper
+
+```typescript
+import { HeaderHelper } from '@twin.org/web';
+
+const header = HeaderHelper.createBearer('token-123');
+
+HeaderHelper.extractBearer(header); // 'token-123'
+```
+
+## Jwk and Jws
+
+```typescript
+import { Jwk, Jws } from '@twin.org/web';
+
+const jwk = Jwk.fromEd25519Public(new Uint8Array(32));
+const compact = Jws.create(
+  {
+    typ: 'JWT',
+    alg: 'EdDSA'
+  },
+  {
+    iss: 'issuer-1'
+  },
+  async signingBytes => signingBytes
+);
+
+Jws.verify(compact, async () => true); // true
+jwk.kty; // 'OKP'
+```
+
+## CookieHelper
+
+```typescript
+import { CookieHelper } from '@twin.org/web';
+
+CookieHelper.createCookie('sessionId', 'abc123', {
+  path: '/',
+  maxAge: 1800,
+  secure: true,
+  httpOnly: true
+}); // 'sessionId=abc123; Max-Age=1800; Path=/; Secure; HttpOnly'
+```
+
+## MimeTypeHelper
+
+```typescript
+import { MimeTypeHelper } from '@twin.org/web';
+
+MimeTypeHelper.detect('avatar.png'); // 'image/png'
+MimeTypeHelper.defaultExtension('application/json'); // 'json'
+```
+
+## FetchError
+
+```typescript
+import { FetchError } from '@twin.org/web';
+
+const error = new FetchError(this.CLASS_NAME, 'fetchFailed', {
+  statusCode: 503,
+  retryable: true
+});
+
+error.toJsonObject().statusCode; // 503
+```

package/docs/reference/classes/CookieHelper.md

@@ -0,0 +1,155 @@
+# Class: CookieHelper
+
+Class to help with cookie operations.
+
+## Constructors
+
+### Constructor
+
+> **new CookieHelper**(): `CookieHelper`
+
+#### Returns
+
+`CookieHelper`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### createCookie() {#createcookie}
+
+> `static` **createCookie**(`cookieName`, `cookieValue`, `options?`): `string`
+
+Create a cookie string.
+
+#### Parameters
+
+##### cookieName
+
+`string`
+
+The name of the cookie.
+
+##### cookieValue
+
+`string`
+
+The value of the cookie.
+
+##### options?
+
+Additional cookie options.
+
+###### secure?
+
+`boolean`
+
+Should this be a secure cookie.
+
+###### httpOnly?
+
+`boolean`
+
+Should this be an http only cookie.
+
+###### sameSite?
+
+`"Strict"` \| `"Lax"` \| `"None"`
+
+The same site option for the cookie.
+
+###### path?
+
+`string`
+
+The path for the cookie.
+
+#### Returns
+
+`string`
+
+The created cookie string.
+
+***
+
+### deleteCookie() {#deletecookie}
+
+> `static` **deleteCookie**(`cookieName`, `options?`): `string`
+
+Create a cookie string which will delete a cookie.
+
+#### Parameters
+
+##### cookieName
+
+`string`
+
+The name of the cookie.
+
+##### options?
+
+Additional cookie options.
+
+###### secure?
+
+`boolean`
+
+Should this be a secure cookie.
+
+###### httpOnly?
+
+`boolean`
+
+Should this be an http only cookie.
+
+###### sameSite?
+
+`"Strict"` \| `"Lax"` \| `"None"`
+
+The same site option for the cookie.
+
+###### path?
+
+`string`
+
+The path for the cookie.
+
+#### Returns
+
+`string`
+
+The created cookie string.
+
+***
+
+### getCookieFromHeaders() {#getcookiefromheaders}
+
+> `static` **getCookieFromHeaders**(`headers`, `cookieName`): `string` \| `undefined`
+
+Get cookies from headers.
+
+#### Parameters
+
+##### headers
+
+`string` \| `string`[] \| `undefined`
+
+The headers to get cookies from.
+
+##### cookieName
+
+`string`
+
+The name of the cookie to get.
+
+#### Returns
+
+`string` \| `undefined`
+
+The cookies found in the headers.

package/docs/reference/classes/FetchError.md

@@ -54,8 +54,460 @@ The cause of the error if we have wrapped another error.
 
 ## Properties
 
-### CLASS\_NAME
+### source? {#source}
+
+> `optional` **source?**: `string`
+
+The source of the error.
+
+#### Inherited from
+
+`BaseError.source`
+
+***
+
+### properties? {#properties}
+
+> `optional` **properties?**: `object`
+
+Any additional information for the error.
+
+#### Index Signature
+
+\[`id`: `string`\]: `unknown`
+
+#### Inherited from
+
+`BaseError.properties`
+
+***
+
+### cause? {#cause}
+
+> `optional` **cause?**: `IError`
+
+The cause of the error.
+
+#### Inherited from
+
+`BaseError.cause`
+
+***
+
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
 Runtime name for the class.
+
+## Methods
+
+### fromError() {#fromerror}
+
+> `static` **fromError**(`err`): `BaseError`
+
+Construct an error from an existing one.
+
+#### Parameters
+
+##### err
+
+`unknown`
+
+The existing error.
+
+#### Returns
+
+`BaseError`
+
+The new instance.
+
+#### Inherited from
+
+`BaseError.fromError`
+
+***
+
+### flatten() {#flatten}
+
+> `static` **flatten**(`err`): `IError`[]
+
+Flatten an error tree.
+
+#### Parameters
+
+##### err
+
+`unknown`
+
+The starting error.
+
+#### Returns
+
+`IError`[]
+
+The list of all internal errors.
+
+#### Inherited from
+
+`BaseError.flatten`
+
+***
+
+### expand() {#expand}
+
+> `static` **expand**(`errors`): `IError` \| `undefined`
+
+Expand an error tree.
+
+#### Parameters
+
+##### errors
+
+`IError`[] \| `undefined`
+
+The list of errors to expand.
+
+#### Returns
+
+`IError` \| `undefined`
+
+The first level error.
+
+#### Inherited from
+
+`BaseError.expand`
+
+***
+
+### isErrorName() {#iserrorname}
+
+> `static` **isErrorName**(`error`, `name`): `error is BaseError`
+
+Test to see if the error has the specified error name.
+
+#### Parameters
+
+##### error
+
+`unknown`
+
+The error to test.
+
+##### name
+
+`string` \| `RegExp`
+
+The name to check for.
+
+#### Returns
+
+`error is BaseError`
+
+True if the error has the name.
+
+#### Inherited from
+
+`BaseError.isErrorName`
+
+***
+
+### isErrorMessage() {#iserrormessage}
+
+> `static` **isErrorMessage**(`error`, `message`): `error is BaseError`
+
+Test to see if the error has the specified error message.
+
+#### Parameters
+
+##### error
+
+`unknown`
+
+The error to test.
+
+##### message
+
+`string` \| `RegExp`
+
+The message to check for.
+
+#### Returns
+
+`error is BaseError`
+
+True if the error has the name.
+
+#### Inherited from
+
+`BaseError.isErrorMessage`
+
+***
+
+### isErrorCode() {#iserrorcode}
+
+> `static` **isErrorCode**(`error`, `code`): `boolean`
+
+Test to see if the error has the specified error code.
+
+#### Parameters
+
+##### error
+
+`unknown`
+
+The error to test.
+
+##### code
+
+`string` \| `RegExp`
+
+The code to check for.
+
+#### Returns
+
+`boolean`
+
+True if the error has the code.
+
+#### Inherited from
+
+`BaseError.isErrorCode`
+
+***
+
+### someErrorName() {#someerrorname}
+
+> `static` **someErrorName**(`error`, `name`): `error is BaseError`
+
+Test to see if any of the errors or children have the given error name.
+
+#### Parameters
+
+##### error
+
+`unknown`
+
+The error to test.
+
+##### name
+
+`string` \| `RegExp`
+
+The name to check for.
+
+#### Returns
+
+`error is BaseError`
+
+True if the error has the name.
+
+#### Inherited from
+
+`BaseError.someErrorName`
+
+***
+
+### someErrorMessage() {#someerrormessage}
+
+> `static` **someErrorMessage**(`error`, `message`): `error is BaseError`
+
+Test to see if any of the errors or children have the given error message.
+
+#### Parameters
+
+##### error
+
+`unknown`
+
+The error to test.
+
+##### message
+
+`string` \| `RegExp`
+
+The message to check for.
+
+#### Returns
+
+`error is BaseError`
+
+True if the error has the name.
+
+#### Inherited from
+
+`BaseError.someErrorMessage`
+
+***
+
+### someErrorClass() {#someerrorclass}
+
+> `static` **someErrorClass**(`error`, `cls`): `error is BaseError`
+
+Test to see if any of the errors or children are from a specific class.
+
+#### Parameters
+
+##### error
+
+`unknown`
+
+The error to test.
+
+##### cls
+
+`string`
+
+The class to check for.
+
+#### Returns
+
+`error is BaseError`
+
+True if the error has the specific class.
+
+#### Inherited from
+
+`BaseError.someErrorClass`
+
+***
+
+### someErrorCode() {#someerrorcode}
+
+> `static` **someErrorCode**(`error`, `code`): `error is BaseError`
+
+Test to see if any of the errors or children have the given error code.
+
+#### Parameters
+
+##### error
+
+`unknown`
+
+The error to test.
+
+##### code
+
+`string` \| `RegExp`
+
+The code to check for.
+
+#### Returns
+
+`error is BaseError`
+
+True if the error has the name.
+
+#### Inherited from
+
+`BaseError.someErrorCode`
+
+***
+
+### isEmpty() {#isempty}
+
+> `static` **isEmpty**(`err`): `boolean`
+
+Is the error empty, i.e. does it have no message, source, properties, or cause?
+
+#### Parameters
+
+##### err
+
+`IError`
+
+The error to check for being empty.
+
+#### Returns
+
+`boolean`
+
+True if the error is empty.
+
+#### Inherited from
+
+`BaseError.isEmpty`
+
+***
+
+### isAggregateError() {#isaggregateerror}
+
+> `static` **isAggregateError**(`err`): `err is AggregateError`
+
+Is the error an aggregate error.
+
+#### Parameters
+
+##### err
+
+`unknown`
+
+The error to check for being an aggregate error.
+
+#### Returns
+
+`err is AggregateError`
+
+True if the error is an aggregate error.
+
+#### Inherited from
+
+`BaseError.isAggregateError`
+
+***
+
+### fromAggregate() {#fromaggregate}
+
+> `static` **fromAggregate**(`err`, `includeStackTrace?`): `IError`[]
+
+Convert the aggregate error to an array of errors.
+
+#### Parameters
+
+##### err
+
+`unknown`
+
+The error to convert.
+
+##### includeStackTrace?
+
+`boolean`
+
+Whether to include the error stack in the model, defaults to false.
+
+#### Returns
+
+`IError`[]
+
+The array of errors.
+
+#### Inherited from
+
+`BaseError.fromAggregate`
+
+***
+
+### toJsonObject() {#tojsonobject}
+
+> **toJsonObject**(`includeStackTrace?`): `IError`
+
+Serialize the error to the error model.
+
+#### Parameters
+
+##### includeStackTrace?
+
+`boolean`
+
+Whether to include the error stack in the model, defaults to false.
+
+#### Returns
+
+`IError`
+
+The error model.
+
+#### Inherited from
+
+`BaseError.toJsonObject`