Add UTF-8 encoding API

docs/malta.config.json

@@ -10,7 +10,8 @@
 			"pages": [
 				["Hex encoding", "/examples/hex"],
 				["Base64 encoding", "/examples/base64"],
-				["Base32 encoding", "/examples/base32"]
+				["Base32 encoding", "/examples/base32"],
+				["UTF-8 encoding", "/examples/utf-8"]
 			]
 		},
 		{

docs/pages/examples/base32.md

@@ -7,9 +7,32 @@ title: "Base32 encoding"
 Use `encodeBase32UpperCase()` or `encodeBase32LowerCase()` to encode data with base32. Use `encodeBase32UpperCaseNoPadding()` or `encodeBase32LowerCaseNoPadding()` to omit padding. `decodeBase32()` requires padding while `decodeBase32IgnorePadding()` ignores padding entirely. Both decoding methods are case insensitive.
 
 ```ts
-import { encodeBase32UpperCase, decodeBase32 } from "@oslojs/encoding";
+import { encodeBase32UpperCase, encodeBase32LowerCase, decodeBase32 } from "@oslojs/encoding";
 
-const data: Uint8Array = new TextEncoder().encode("hello world");
+const data = new Uint8Array();
 const encoded = encodeBase32UpperCase(data);
+const encoded = encodeBase32LowerCase(data);
 const decoded = decodeBase32(encoded);
 ```
+
+```ts
+import {
+	encodeBase32UpperCaseNoPadding,
+	encodeBase32LowerCaseNoPadding,
+	decodeBase32IgnorePadding
+} from "@oslojs/encoding";
+
+const data = new Uint8Array();
+const encoded = encodeBase32UpperCaseNoPadding(data);
+const encoded = encodeBase32LowerCaseNoPadding(data);
+const decoded = decodeBase32IgnorePadding(encoded);
+```
+
+To encode strings, use [`encodeUTF8()`](/examples/utf-8) to UTF-8 encode it first.
+
+```ts
+import { encodeUTF8, encodeBase32UpperCase } from "@oslojs/encoding";
+
+const data = encodeUTF8("Hello world!");
+const encoded = encodeBase32UpperCase(data);
+```

docs/pages/examples/base64.md

@@ -9,15 +9,48 @@ Use `encodeBase64()` or `encodeBase64NoPadding()` to omit padding. `decodeBase64
 ```ts
 import { encodeBase64, decodeBase64 } from "@oslojs/encoding";
 
-const data: Uint8Array = new TextEncoder().encode("hello world");
+const data = new Uint8Array();
 const encoded = encodeBase64(data);
 const decoded = decodeBase64(encoded);
 ```
 
+```ts
+import { encodeBase64NoPadding, decodeBase64IgnorePadding } from "@oslojs/encoding";
+
+const data = new Uint8Array();
+const encoded = encodeBase64NoPadding(data);
+const decoded = decodeBase64IgnorePadding(encoded);
+```
+
 ```ts
 import { encodeBase64url, decodeBase64url } from "@oslojs/encoding";
 
-const data: Uint8Array = new TextEncoder().encode("hello world");
+const data = new Uint8Array();
 const encoded = encodeBase64url(data);
 const decoded = decodeBase64url(encoded);
 ```
+
+```ts
+import { encodeBase64, decodeBase64 } from "@oslojs/encoding";
+
+const data = new Uint8Array();
+const encoded = encodeBase64(data);
+const decoded = decodeBase64(encoded);
+```
+
+```ts
+import { encodeBase64urlNoPadding, decodeBase64urlIgnorePadding } from "@oslojs/encoding";
+
+const data = new Uint8Array();
+const encoded = encodeBase64urlNoPadding(data);
+const decoded = decodeBase64urlIgnorePadding(encoded);
+```
+
+To encode strings, use [`encodeUTF8()`](/examples/utf-8) to UTF-8 encode it first.
+
+```ts
+import { encodeUTF8, encodeBase64 } from "@oslojs/encoding";
+
+const data = encodeUTF8("Hello world!");
+const encoded = encodeBase64(data);
+```

docs/pages/examples/hex.md

@@ -7,10 +7,19 @@ title: "Hex encoding"
 Use `encodeHexUpperCase()` or `encodeHexLowerCase()` to encode data and `decodeHex()` to decode hex-encoded strings. `decodeHex()` is case-insensitive.
 
 ```ts
-import { encodeUpperCase, encodeHexLowerCase, decodeHex } from "@oslojs/encoding";
+import { encodeHexUpperCase, encodeHexLowerCase, decodeHex } from "@oslojs/encoding";
 
-const data: Uint8Array = new TextEncoder().encode("hello world");
+const data = new Uint8Array();
 const hex = encodeHexUpperCase(data);
 const hex = encodeHexLowerCase(data);
 const decoded = decodeHex(hex);
 ```
+
+To encode strings, use [`encodeUTF8()`](/examples/utf-8) to UTF-8 encode it first.
+
+```ts
+import { encode, encodeHexUpperCase } from "@oslojs/encoding";
+
+const data = encodeUTF8("Hello world!");
+const encoded = encodeHexUpperCase(data);
+```

docs/pages/examples/utf-8.md

@@ -0,0 +1,23 @@
+---
+title: "UTF-8"
+---
+
+# UTF-8
+
+Use `encodeUTF8()` to UTF-8 encode strings to byte sequences. Use `decodeUTF8()` to decode into a string or use `decodeUTF8IntoCodePoints()` to decode into an array of Unicode code points.
+
+Use `isValidUTF8Encoding()` to validate a UTF-8 byte sequence without decoding it.
+
+```ts
+import {
+	encodeUTF8,
+	decodeUTF8,
+	decodeUTF8IntoCodePoints,
+	isValidUTF8Encoding
+} from "@oslojs/encoding";
+
+const encoded = encodeUTF8("Hello world!");
+const decoded = decodeUTF8(encoded);
+const decodedCodePoints = decodeUTF8IntoCodePoints(encoded);
+const valid = isValidUTF8Encoding(encoded);
+```

docs/pages/reference/main/decodeUTF8.md

@@ -0,0 +1,21 @@
+---
+title: "decodeUTF8()"
+---
+
+# decodeUTF8()
+
+UTF-8 decodes a byte sequence into a string. Throws a `TypeError` on invalid character encodings:
+
+- Overlong encodings.
+- Code points greater than x10ffff.
+- High and low surrogates used by UTF-16.
+- Leading continuation byte.
+- Non-continuation byte before the end of a character.
+
+The byte-order mark character is decoded into an empty string.
+
+Since this method throws when the string contains high and low surrogates, it behaves slightly different from the `TextEncoder.encode()` method in the standard web API.
+
+```ts
+function decodeUTF8(bytes: Uint8Array): string;
+```

docs/pages/reference/main/decodeUTF8IntoCodePoints.md

@@ -0,0 +1,17 @@
+---
+title: "decodeUTF8()"
+---
+
+# decodeUTF8()
+
+UTF-8 decodes a byte sequence into an array of code points (uint32). Throws a `TypeError` on invalid character encodings:
+
+- Overlong encodings.
+- Code points greater than x10ffff.
+- High and low surrogates used by UTF-16.
+- Leading continuation byte.
+- Non-continuation byte before the end of a character.
+
+```ts
+function decodeUTF8IntoCodePoints(bytes: Uint8Array): Uint32Array;
+```

docs/pages/reference/main/encodeUTF8.md

@@ -0,0 +1,14 @@
+---
+title: "encodeUTF8()"
+---
+
+# encodeUTF8()
+
+UTF-8 encodes a string into a byte sequence. Throws a `TypeError` on invalid code points:
+
+- Code points greater than 0x10ffff.
+- High and low surrogates used by UTF-16.
+
+```ts
+function encodeUTF8(s: string): Uint8Array;
+```

docs/pages/reference/main/index.md

@@ -13,6 +13,8 @@ title: "@oslojs/encoding"
 - [`decodeBase64url()`](/reference/main/decodeBase64url)
 - [`decodeBase64urlIgnorePadding()`](/reference/main/decodeBase64urlIgnorePadding)
 - [`decodeHex()`](/reference/main/decodeHex)
+- [`decodeUTF8()`](/reference/main/decodeUTF8)
+- [`decodeUTF8IntoCodePoints()`](/reference/main/decodeUTF8IntoCodePoints)
 - [`encodeBase32LowerCase()`](/reference/main/encodeBase32LowerCase)
 - [`encodeBase32LowerCaseNoPadding()`](/reference/main/encodeBase32LowerCaseNoPadding)
 - [`encodeBase32UpperCase()`](/reference/main/encodeBase32UpperCase)
@@ -23,5 +25,7 @@ title: "@oslojs/encoding"
 - [`encodeBase64urlNoPadding()`](/reference/main/encodeBase64urlNoPadding)
 - [`encodeHexLowerCase()`](/reference/main/encodeHexLowerCase)
 - [`encodeHexUpperCase()`](/reference/main/encodeHexUpperCase)
+- [`encodeUTF8()`](/reference/main/encodeUTF8)
+- [`isValidUTF8Encoding()`](/reference/main/isValidUTF8Encoding)
 - _Replaced_ [`encodeBase32()`](/reference/main/encodeBase32)
 - _Replaced_ [`encodeBase32NoPadding()`](/reference/main/encodeBase32NoPadding)

docs/pages/reference/main/isValidUTF8Encoding.md

@@ -0,0 +1,17 @@
+---
+title: "isValidUTF8Encoding()"
+---
+
+# isValidUTF8Encoding()
+
+Reports whether the byte sequence is a valid UTF-8 encoding. Returns `false` on:
+
+- Overlong encodings.
+- Code points greater than x10ffff.
+- High and low surrogates used by UTF-16.
+- Leading continuation byte.
+- Non-continuation byte before the end of a character.
+
+```ts
+function isValidUTF8Encoding(bytes: Uint8Array): boolean;
+```

src/index.ts

@@ -19,3 +19,4 @@ export {
 	decodeBase64url,
 	decodeBase64urlIgnorePadding
 } from "./base64.js";
+export { encodeUTF8, decodeUTF8, decodeUTF8IntoCodePoints, isValidUTF8Encoding } from "./utf-8.js";