diff --git a/LICENSE b/LICENSE index db30d48..4d23f73 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2020 sciencesakura +Copyright (c) 2025 sciencesakura Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index d076603..1cfaa3c 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ -# mutf-8: Encoder/Decoder for Modified UTF-8 +# mutf-8: An Encoder and Decoder for Modified UTF-8 ![](https://github.com/sciencesakura/mutf-8/actions/workflows/build.yaml/badge.svg) [![npm version](https://badge.fury.io/js/mutf-8.svg)](https://badge.fury.io/js/mutf-8) ## What is Modified UTF-8? -Modified UTF-8 (MUTF-8) is used in the Java platform, such as the class file format and object serialization. +Modified UTF-8 is a variant of UTF-8 used in the Java platform, such as the class file format and object serialization. -See [The Java Virtual Machine Specification, Java SE 21 Edition, section 4.4.7](https://docs.oracle.com/javase/specs/jvms/se21/html/jvms-4.html#jvms-4.4.7) for details. +See [The Java Virtual Machine Specification, Java SE 21 Edition, Section 4.4.7](https://docs.oracle.com/javase/specs/jvms/se21/html/jvms-4.html#jvms-4.4.7) for details. ## Installation @@ -14,13 +14,18 @@ See [The Java Virtual Machine Specification, Java SE 21 Edition, section 4.4.7]( npm install mutf-8 ``` +If you want to use the stream API, install the `mutf-8-stream` module instead. + +```sh +npm install mutf-8-stream +``` + ## Usage -The APIs are similar to [WHATWG TextEncoder/TextDecoder](https://encoding.spec.whatwg.org/). +The APIs are similar to [WHATWG Encoding](https://encoding.spec.whatwg.org/). ```javascript -import { MUtf8Decoder, MUtf8Encoder } from "mutf-8"; // ES Modules -// const { MUtf8Decoder, MUtf8Encoder } = require("mutf-8"); // CommonJS +import { MUtf8Decoder, MUtf8Encoder } from "mutf-8"; const encoder = new MUtf8Encoder(); const code = encoder.encode("Hello 世界! Santé🍻"); @@ -36,7 +41,27 @@ const text = decoder.decode(code); // Hello 世界! Santé🍻 ``` -See [API reference](https://sciencesakura.github.io/mutf-8/) for details. +```javascript +import { MUtf8DecoderStream, MUtf8EncoderStream } from "mutf-8-stream"; + +await getLargeTextAsStream() + .pipeThrough(new MUtf8EncoderStream()) + .pipeTo(new WritableStream({ + write(chunk) { + // Handle the encoded chunk + } + })); + +await getLargeBinaryAsStream() + .pipeThrough(new MUtf8DecoderStream()) + .pipeTo(new WritableStream({ + write(chunk) { + // Handle the decoded chunk + } + })); +``` + +See [API Reference](https://sciencesakura.github.io/mutf-8/) for details. ## License diff --git a/biome.json b/biome.json index 6a643fa..cbb1c6e 100644 --- a/biome.json +++ b/biome.json @@ -7,7 +7,7 @@ }, "files": { "ignoreUnknown": false, - "ignore": ["**/testdata-*"] + "ignore": ["**/testdata.*"] }, "formatter": { "enabled": true, diff --git a/packages/mutf-8-stream/package.json b/packages/mutf-8-stream/package.json index e2d6781..6b647a9 100644 --- a/packages/mutf-8-stream/package.json +++ b/packages/mutf-8-stream/package.json @@ -1,7 +1,7 @@ { "name": "mutf-8-stream", "version": "1.2.0", - "description": "An encoder/decoder for Modified UTF-8 (MUTF-8) which is used in the Java platform such as the class file format and the object serialization.", + "description": "An encoder and decoder for Modified UTF-8 which is used in the Java platform such as the class file format and object serialization.", "keywords": [ "charset", "encoding", diff --git a/packages/mutf-8-stream/src/index.ts b/packages/mutf-8-stream/src/index.ts index fa0e8cb..cec2152 100644 --- a/packages/mutf-8-stream/src/index.ts +++ b/packages/mutf-8-stream/src/index.ts @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MIT + import { type AllowSharedBufferSource, MUtf8Decoder, MUtf8Encoder, type TextDecoderOptions } from "mutf-8"; /** @@ -6,13 +7,17 @@ import { type AllowSharedBufferSource, MUtf8Decoder, MUtf8Encoder, type TextDeco * * @example * ```ts - * // Convert Modified UTF-8 stream to UTF-8 stream. - * await mutf8Stream.pipeThrough(new MUtf8DecoderStream()) - * .pipeThrough(new TextEncoderStream()) - * .pipeTo(destination); + * await getLargeBinaryAsStream() + * .pipeThrough(new MUtf8DecoderStream()) + * .pipeTo(new WritableStream({ + * write(chunk) { + * // Handle the decoded chunk + * } + * })); * ``` * - * @see {@link https://encoding.spec.whatwg.org/} + * @see {@link https://encoding.spec.whatwg.org/#interface-textdecoderstream} + * @since v1.2.0 */ export class MUtf8DecoderStream extends TransformStream { #decoder: MUtf8Decoder; @@ -39,8 +44,6 @@ export class MUtf8DecoderStream extends TransformStream { /** @@ -77,9 +84,6 @@ export class MUtf8EncoderStream extends TransformStream { return "mutf-8"; } - /** - * Creates an instance of `MUtf8EncoderStream`. - */ constructor() { const encoder = new MUtf8Encoder(); super({ diff --git a/packages/mutf-8/package.json b/packages/mutf-8/package.json index 0ba67ed..1c261ec 100644 --- a/packages/mutf-8/package.json +++ b/packages/mutf-8/package.json @@ -1,7 +1,7 @@ { "name": "mutf-8", "version": "1.2.0", - "description": "An encoder/decoder for Modified UTF-8 (MUTF-8) which is used in the Java platform such as the class file format and the object serialization.", + "description": "An encoder and decoder for Modified UTF-8 which is used in the Java platform such as the class file format and object serialization.", "keywords": [ "charset", "encoding", diff --git a/packages/mutf-8/src/index.ts b/packages/mutf-8/src/index.ts index 7d5612f..debb4e0 100644 --- a/packages/mutf-8/src/index.ts +++ b/packages/mutf-8/src/index.ts @@ -61,7 +61,7 @@ export type AllowSharedBufferSource = ArrayBuffer | SharedArrayBuffer | ArrayBuf * // Hello 世界! * ``` * - * @see {@link https://encoding.spec.whatwg.org/} + * @see {@link https://encoding.spec.whatwg.org/#interface-textdecoder} */ export class MUtf8Decoder { #fatal: boolean; @@ -92,11 +92,9 @@ export class MUtf8Decoder { } /** - * Creates an instance of MUtf8Decoder. - * * @param label - The label of the decoder. Must be `"mutf-8"` or `"mutf8"`. * @param options - The options for the decoder. - * @throws {RangeError} If the `label` is an invalid value. + * @throws `RangeError` If the `label` is an invalid value. */ constructor(label = "mutf-8", options: TextDecoderOptions = {}) { const normalizedLabel = label.toLowerCase(); @@ -113,7 +111,7 @@ export class MUtf8Decoder { * @param input - The bytes to be decoded. * @param options - The options for decoding. * @returns The resultant string after decoding. - * @throws {TypeError} If {@link fatal} is `true` and the `input` contains invalid bytes. + * @throws `TypeError` If {@link fatal} is `true` and the `input` contains invalid bytes. */ decode(input: AllowSharedBufferSource, options: TextDecodeOptions = {}): string { const stream = options.stream ?? false; @@ -215,7 +213,7 @@ export class MUtf8Decoder { * // ] * ``` * - * @see {@link https://encoding.spec.whatwg.org/} + * @see {@link https://encoding.spec.whatwg.org/#interface-textencoder} */ export class MUtf8Encoder { /** diff --git a/scripts/gen-testdatacode.groovy b/scripts/gen-testdatacode.groovy index e92fa7a..ff9edc8 100755 --- a/scripts/gen-testdatacode.groovy +++ b/scripts/gen-testdatacode.groovy @@ -41,7 +41,6 @@ def decode = { binary -> def generateTestDataCode = { jsonFile -> def code = new StringBuilder('// This file is generated by scripts/gen-testdatacode.groovy\n\n') - code << '// biome-ignore format:\n' code << 'export default [' new JsonSlurper().parse(jsonFile).each { def binary = encode(it.text) diff --git a/testdata.mts b/testdata.mts index 57de858..f06309c 100644 --- a/testdata.mts +++ b/testdata.mts @@ -1,6 +1,5 @@ // This file is generated by scripts/gen-testdatacode.groovy -// biome-ignore format: export default [ { name: "The null character",