@shayc/open-board-format 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @shayc/open-board-format
 
+## 0.5.0
+
+### Minor Changes
+
+- 24535c7: Throw a typed `OBFError` instead of plain `Error`. Every failure now carries a discriminated `error.info`, so consumers branch on `error.info.code` (e.g. `"missing-resource"`, `"invalid-board"`, `"not-zip"`) and read structured fields off each variant — no message parsing.
+
+  - New exports: `OBFError` (class), and the `OBFErrorInfo`, `OBFErrorCode`, and `OBFIssue` types.
+  - Validation failures (`invalid-board`, `invalid-manifest`) expose the Zod `issues` list on `error.info`. The underlying error — the `ZodError`, or the `JSON.parse`/fflate failure for `not-json`/`unreadable-zip`/`zip-failed` — is always on the standard `error.cause` and never duplicated on `info`.
+  - An `internal` code marks a library-invariant violation (a bug here), not something callers can recover from.
+  - **Breaking:** thrown errors are now `OBFError` (`error.name` is `"OBFError"`) and message strings changed. Branch on `error.info.code` rather than matching `error.message`. The internal `buildJsonParseErrorMessage` helper was removed.
+
+## 0.4.2
+
+### Patch Changes
+
+- d2beda3: docs: ship the OBF spec mirror (`docs/external/open-board-format.md`) in the npm package
+
+  The README already points at this file; including it makes that link resolve
+  inside `node_modules` and gives offline tooling and coding agents the full
+  format semantics (specialty actions, string-list fallback, ID uniqueness)
+  that type declarations can't carry.
+
 ## 0.4.1
 
 ### Patch Changes

package/README.md

@@ -175,16 +175,52 @@ import { OBFButtonSchema, OBFManifestSchema } from "@shayc/open-board-format";
 
 ## Errors
 
-All failures throw plain `Error`. The message identifies what failed, typically with one of these prefixes:
+Every failure throws an `OBFError`. Branch on `error.info.code` — a discriminated union where each `code` carries exactly the fields relevant to that failure. Don't match on `error.message`; the message is human-readable and may change between releases.
 
-- `Invalid OBF:` — schema validation rejected an OBF board.
-- `Invalid OBZ:` — the package was rejected.
-  - On read: not a ZIP, missing manifest, the manifest references a board file not in the archive, or a board's `id` differs from the ID the manifest declares for it.
-  - On write (`createOBZ`): `rootBoardId` matches no board, two boards share the same `id`, a board fails validation, two boards map the same media `id` to conflicting paths, a declared image/sound `path` has no matching resource, or a resource would overwrite a generated entry.
-- `Invalid manifest:` — `manifest.json` failed to parse or validate, including a `root` that is not listed in `paths.boards`.
-- `Failed to unzip:` / `Failed to zip:` — the archive could not be decompressed (truncated or corrupt despite a valid ZIP signature) or compressed.
+```ts
+import { loadBoard, OBFError } from "@shayc/open-board-format";
+
+try {
+  await loadBoard(file);
+} catch (error) {
+  if (!(error instanceof OBFError)) throw error;
+
+  switch (error.info.code) {
+    case "missing-resource":
+      // `kind`, `mediaId`, and `path` are all typed and present here
+      console.warn(`Missing ${error.info.kind} at ${error.info.path}`);
+      break;
+    case "invalid-board":
+      // `issues` is the Zod issue list — which field failed and why
+      console.error(error.info.issues);
+      break;
+    default:
+      console.error(error.message);
+  }
+}
+```
 
-When the root cause is a `JSON.parse` failure, the original error is preserved as `error.cause`. For finer-grained validation, drop one level down and use the Zod schemas directly with `safeParse` — the `issues` array tells you exactly which field failed.
+The `code` values, grouped by what they describe:
+
+| Group       | `info.code`         | Key fields (on `info`)           |
+| ----------- | ------------------- | -------------------------------- |
+| Decoding    | `not-json`          | `source`                         |
+|             | `not-zip`           | —                                |
+|             | `unreadable-zip`    | —                                |
+| Validation  | `invalid-board`     | `issues`, `boardId?`             |
+|             | `invalid-manifest`  | `issues`                         |
+| Read (OBZ)  | `missing-manifest`  | —                                |
+|             | `missing-board`     | `boardId`, `path`                |
+|             | `board-id-mismatch` | `path`, `declaredId`, `actualId` |
+| Write (OBZ) | `unknown-root`      | `rootBoardId`                    |
+|             | `duplicate-board`   | `boardId`                        |
+|             | `missing-resource`  | `kind`, `mediaId`, `path`        |
+|             | `conflicting-paths` | `kind`, `mediaId`, `paths`       |
+|             | `path-collision`    | `path`                           |
+|             | `zip-failed`        | —                                |
+| Internal    | `internal`          | `detail`                         |
+
+`OBFErrorInfo` and `OBFErrorCode` are exported for exhaustive handling. The underlying error, when there is one, is always on the standard `error.cause` — never duplicated on `info`. Validation failures (`invalid-board`, `invalid-manifest`) put the `ZodError` there, so you can call `z.treeifyError(error.cause)` for nested, UI-friendly output, while `info.issues` (Zod's issue type, re-exported as `OBFIssue`) gives you the flat list directly. For `not-json` / `*-zip` failures `error.cause` is the underlying parser or fflate error. An `internal` code signals a bug in this library that callers can't recover from — please report it.
 
 ## Security
 

package/dist/index.d.mts

@@ -354,6 +354,89 @@ declare const OBFManifestSchema: z.ZodObject<{
  */
 type OBFManifest = z.infer<typeof OBFManifestSchema>;
 //#endregion
+//#region src/errors.d.ts
+/**
+ * A single schema validation problem — Zod's issue shape, re-exported under a
+ * domain name. `z.core.$ZodIssue` is the type Zod v4 designates for libraries
+ * built on it (the bare `z.ZodIssue` is deprecated in its favor); aliasing it
+ * gives consumers a stable OBF name without reaching into Zod's `core` export.
+ */
+type OBFIssue = z.core.$ZodIssue;
+/**
+ * Discriminated description of why an {@link OBFError} was thrown.
+ *
+ * Switch on `code`; each variant carries the fields relevant to it. When a
+ * failure wraps an underlying error it lives on the standard `error.cause`,
+ * never duplicated here. The only optional field is `invalid-board`'s
+ * `boardId`, absent when validation runs on a value with no known id.
+ */
+type OBFErrorInfo = /** Input was not parseable JSON. */{
+  code: "not-json";
+  source: "board" | "manifest";
+} /** An OBZ archive was expected, but the bytes are not a ZIP. */ | {
+  code: "not-zip";
+} /** A ZIP archive could not be decompressed. */ | {
+  code: "unreadable-zip";
+} /** A board failed schema validation. `boardId` is set when known. */ | {
+  code: "invalid-board";
+  boardId?: string;
+  issues: readonly OBFIssue[];
+} /** A manifest failed schema validation. */ | {
+  code: "invalid-manifest";
+  issues: readonly OBFIssue[];
+} /** The archive has no `manifest.json`. */ | {
+  code: "missing-manifest";
+} /** A board the manifest declares is absent from the archive. */ | {
+  code: "missing-board";
+  boardId: string;
+  path: string;
+} /** A board's `id` disagrees with the id the manifest declares for it. */ | {
+  code: "board-id-mismatch";
+  path: string;
+  declaredId: string;
+  actualId: string;
+} /** `rootBoardId` matches none of the supplied boards. */ | {
+  code: "unknown-root";
+  rootBoardId: string;
+} /** Two supplied boards share the same `id`. */ | {
+  code: "duplicate-board";
+  boardId: string;
+} /** A board declares a media `path` with no matching resource. */ | {
+  code: "missing-resource";
+  kind: "image" | "sound";
+  mediaId: string;
+  path: string;
+} /** Two boards declare the same media id with different paths. */ | {
+  code: "conflicting-paths";
+  kind: "image" | "sound";
+  mediaId: string;
+  paths: [string, string];
+} /** A supplied resource would overwrite a generated board or the manifest. */ | {
+  code: "path-collision";
+  path: string;
+} /** The archive could not be compressed. */ | {
+  code: "zip-failed";
+} /** An internal invariant was violated — a bug in this library; please report. */ | {
+  code: "internal";
+  detail: string;
+};
+/** Every `code` an {@link OBFError} can carry. */
+type OBFErrorCode = OBFErrorInfo["code"];
+/**
+ * The single error type thrown by `@shayc/open-board-format`.
+ *
+ * Branch on {@link OBFError.info} (a discriminated {@link OBFErrorInfo}) rather
+ * than parsing {@link OBFError.message}. Any underlying error — a `JSON.parse`
+ * failure, a `ZodError`, or an fflate error — is on the standard `error.cause`.
+ */
+declare class OBFError extends Error {
+  /** Structured, discriminated description of the failure. */
+  readonly info: OBFErrorInfo;
+  constructor(info: OBFErrorInfo, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
 //#region src/obf.d.ts
 /**
  * Parse a JSON string into a validated OBF board.
@@ -364,7 +447,8 @@ type OBFManifest = z.infer<typeof OBFManifestSchema>;
  * @param json - The JSON string to parse.
  * @returns The validated board object.
  *
- * @throws {Error} If the JSON is malformed or fails schema validation.
+ * @throws {@link OBFError} with `info.code` `"not-json"` if the JSON is
+ *   malformed, or `"invalid-board"` if it fails schema validation.
  */
 declare function parseOBF(json: string): OBFBoard;
 /**
@@ -376,7 +460,8 @@ declare function parseOBF(json: string): OBFBoard;
  * @param file - A `File` handle pointing to an `.obf` file.
  * @returns The validated board object.
  *
- * @throws {Error} If the file content is malformed or fails schema validation.
+ * @throws {@link OBFError} with `info.code` `"not-json"` if the file content is
+ *   malformed, or `"invalid-board"` if it fails schema validation.
  */
 declare function loadOBF(file: File): Promise<OBFBoard>;
 /**
@@ -385,7 +470,8 @@ declare function loadOBF(file: File): Promise<OBFBoard>;
  * @param data - The value to validate.
  * @returns The validated board object.
  *
- * @throws {Error} If the value fails schema validation.
+ * @throws {@link OBFError} with `info.code` `"invalid-board"` if the value fails
+ *   schema validation. `info.issues` holds the underlying Zod issues.
  */
 declare function validateOBF(data: unknown): OBFBoard;
 /**
@@ -426,7 +512,8 @@ interface ParsedOBZ {
  * @param file - A `File` handle pointing to an `.obz` archive.
  * @returns The parsed manifest, boards, root board, and binary resources.
  *
- * @throws {Error} Same failures as {@link extractOBZ}, which this delegates to.
+ * @throws {@link OBFError} — the same failures as {@link extractOBZ}, which
+ *   this delegates to.
  */
 declare function loadOBZ(file: File): Promise<ParsedOBZ>;
 /**
@@ -437,9 +524,10 @@ declare function loadOBZ(file: File): Promise<ParsedOBZ>;
  *          the resolved root board, and a map of file paths to their
  *          binary content.
  *
- * @throws {Error} If the archive is not a valid ZIP, the manifest is missing,
- *   a board declared in the manifest is missing or fails validation, or a
- *   board's `id` differs from the ID the manifest declares for it.
+ * @throws {@link OBFError}; branch on `info.code`: `"not-zip"`,
+ *   `"unreadable-zip"`, `"missing-manifest"`, `"not-json"` or
+ *   `"invalid-manifest"` (bad manifest), `"missing-board"`,
+ *   `"board-id-mismatch"`, or `"invalid-board"` (a board fails validation).
  */
 declare function extractOBZ(archive: ArrayBuffer): Promise<ParsedOBZ>;
 /**
@@ -449,7 +537,8 @@ declare function extractOBZ(archive: ArrayBuffer): Promise<ParsedOBZ>;
  * @param json - A JSON string representing the manifest.
  * @returns The validated manifest object.
  *
- * @throws {Error} If the JSON is malformed or fails schema validation.
+ * @throws {@link OBFError} with `info.code` `"not-json"` if the JSON is
+ *   malformed, or `"invalid-manifest"` if it fails schema validation.
  */
 declare function parseManifest(json: string): OBFManifest;
 /**
@@ -458,17 +547,19 @@ declare function parseManifest(json: string): OBFManifest;
  * A manifest is generated automatically from the supplied boards,
  * using the `rootBoardId` to designate the entry-point board.
  *
+ * Every failure is an {@link OBFError}; branch on `info.code`.
+ *
  * @param boards - The boards to include in the archive.
  * @param rootBoardId - The ID of the board that serves as the archive's entry point.
  * @param resources - Optional map of file paths to binary content (images, sounds, etc.).
  * @returns A `Blob` containing the compressed OBZ archive.
  *
- * @throws {Error} If `rootBoardId` does not match any of the supplied boards.
- * @throws {Error} If two supplied boards share the same ID.
- * @throws {Error} If a supplied board fails schema validation.
- * @throws {Error} If two boards declare the same media ID with conflicting paths.
- * @throws {Error} If a board declares an image or sound `path` with no matching entry in `resources`.
- * @throws {Error} If a `resources` entry would overwrite the generated `manifest.json` or a board file.
+ * @throws {@link OBFError} `"unknown-root"` if `rootBoardId` does not match any of the supplied boards.
+ * @throws {@link OBFError} `"duplicate-board"` if two supplied boards share the same ID.
+ * @throws {@link OBFError} `"invalid-board"` if a supplied board fails schema validation.
+ * @throws {@link OBFError} `"conflicting-paths"` if two boards declare the same media ID with conflicting paths.
+ * @throws {@link OBFError} `"missing-resource"` if a board declares an image or sound `path` with no matching entry in `resources`.
+ * @throws {@link OBFError} `"path-collision"` if a `resources` entry would overwrite the generated `manifest.json` or a board file.
  */
 declare function createOBZ(boards: OBFBoard[], rootBoardId: string, resources?: Map<string, Uint8Array | ArrayBuffer>): Promise<Blob>;
 //#endregion
@@ -508,8 +599,9 @@ type LoadedBoard = {
  * @param input - A `File` handle or `ArrayBuffer` holding `.obf` or `.obz` content.
  * @returns A discriminated union tagged by `format`.
  *
- * @throws {Error} If an OBZ archive is malformed or its manifest is missing,
- *   or if an OBF board is malformed or fails schema validation.
+ * @throws {@link OBFError} — the OBZ failures of {@link extractOBZ} when the
+ *   input is an archive, or the OBF failures of {@link parseOBF} otherwise.
+ *   Branch on `error.info.code`.
  */
 declare function loadBoard(input: File | ArrayBuffer): Promise<LoadedBoard>;
 //#endregion
@@ -523,7 +615,8 @@ declare function loadBoard(input: File | ArrayBuffer): Promise<LoadedBoard>;
  * @param archive - The ZIP archive as an `ArrayBuffer`.
  * @returns A map of file paths to their decompressed content.
  *
- * @throws {Error} If the archive is corrupt or cannot be decompressed.
+ * @throws {@link OBFError} with `info.code` `"unreadable-zip"` if the archive is
+ *   corrupt or cannot be decompressed.
  */
 declare function unzip(archive: ArrayBuffer): Promise<Map<string, Uint8Array>>;
 /**
@@ -536,7 +629,8 @@ declare function unzip(archive: ArrayBuffer): Promise<Map<string, Uint8Array>>;
  * @param entries - A map of file paths to their content bytes.
  * @returns The compressed archive as a `Uint8Array`.
  *
- * @throws {Error} If fflate fails to compress an entry.
+ * @throws {@link OBFError} with `info.code` `"zip-failed"` if fflate fails to
+ *   compress an entry.
  */
 declare function zip(entries: Map<string, Uint8Array | ArrayBuffer>): Promise<Uint8Array>;
 /**
@@ -548,5 +642,5 @@ declare function zip(entries: Map<string, Uint8Array | ArrayBuffer>): Promise<Ui
  */
 declare function isZip(archive: ArrayBuffer): boolean;
 //#endregion
-export { type LoadedBoard, type OBFBoard, OBFBoardSchema, type OBFButton, type OBFButtonAction, OBFButtonActionSchema, OBFButtonSchema, type OBFFormatVersion, OBFFormatVersionSchema, type OBFGrid, OBFGridSchema, type OBFID, OBFIDSchema, type OBFImage, OBFImageSchema, type OBFLicense, OBFLicenseSchema, type OBFLoadBoard, OBFLoadBoardSchema, type OBFLocaleCode, OBFLocaleCodeSchema, type OBFLocalizedStrings, OBFLocalizedStringsSchema, type OBFManifest, OBFManifestSchema, type OBFMedia, OBFMediaSchema, type OBFSound, OBFSoundSchema, type OBFSpecialtyAction, OBFSpecialtyActionSchema, type OBFSpellingAction, OBFSpellingActionSchema, type OBFStrings, OBFStringsSchema, type OBFSymbolInfo, OBFSymbolInfoSchema, type ParsedOBZ, createOBZ, extractOBZ, isZip, loadBoard, loadOBF, loadOBZ, parseManifest, parseOBF, stringifyOBF, unzip, validateOBF, zip };
+export { type LoadedBoard, type OBFBoard, OBFBoardSchema, type OBFButton, type OBFButtonAction, OBFButtonActionSchema, OBFButtonSchema, OBFError, type OBFErrorCode, type OBFErrorInfo, type OBFFormatVersion, OBFFormatVersionSchema, type OBFGrid, OBFGridSchema, type OBFID, OBFIDSchema, type OBFImage, OBFImageSchema, type OBFIssue, type OBFLicense, OBFLicenseSchema, type OBFLoadBoard, OBFLoadBoardSchema, type OBFLocaleCode, OBFLocaleCodeSchema, type OBFLocalizedStrings, OBFLocalizedStringsSchema, type OBFManifest, OBFManifestSchema, type OBFMedia, OBFMediaSchema, type OBFSound, OBFSoundSchema, type OBFSpecialtyAction, OBFSpecialtyActionSchema, type OBFSpellingAction, OBFSpellingActionSchema, type OBFStrings, OBFStringsSchema, type OBFSymbolInfo, OBFSymbolInfoSchema, type ParsedOBZ, createOBZ, extractOBZ, isZip, loadBoard, loadOBF, loadOBZ, parseManifest, parseOBF, stringifyOBF, unzip, validateOBF, zip };
 //# sourceMappingURL=index.d.mts.map