feat: export error types via custom-error-creator (#52)

[gmaclennan]

Closes #52.

What

Switches the error module to custom-error-creator (the same library @comapeo/core uses) and adds a dependency-light ./errors.js public export so CoMapeo mobile can identify invalid-file errors crossing the nodejs-mobile IPC bridge — to show a friendly message and to avoid reporting expected user-input errors to Sentry.

Changes

• src/lib/errors.js — every error class is now created with createErrorClass(...). Each carries a stable static .code (e.g. MISSING_CATEGORIES_ERROR, INVALID_ZIP_FILE_ERROR). Codes are the screaming-snake form of the existing class names, so .name is preserved and any existing name-based checks keep working. isParseError / isInvalidFileError now match on the stable .code. Dropped the node:path dependency.
• src/errors.js (new) — the public, frontend-safe entry. Re-exports the error classes and typeguards. Its import graph pulls in only custom-error-creator (zero deps) and pure constants — no yauzl, node streams, or valibot — so it is safe to import into a React Native bundle without the Reader/Writer.
• package.json — adds the ./errors.js export entry and the custom-error-creator dependency.
• tsconfig.npm.json — includes src/errors.js so dist/errors.d.ts is emitted.
• Errors with dynamic, multi-line messages (CategoryRefError, InvalidCategorySelectionError, DuplicateTagsError, UnsupportedFileVersionError, MissingCategoriesError) use custom-error-creator@1.3.0's typed function-message param, so the message building lives in the error definition and call sites pass structured params (new CategoryRefError({ missingRefs, property })). SchemaError keeps building its message at the call site so valibot stays out of the frontend-safe module.

No HTTP status is set on the errors (optional in custom-error-creator@1.3.0) since these don't map to HTTP statuses. Recognise errors by .code.

Consumer usage

import { isInvalidFileError, MissingCategoriesError } from 'comapeocat/errors.js'
// or check err.code === 'MISSING_CATEGORIES_ERROR'

Verification

• tsc -p tsconfig.json clean except one pre-existing, unrelated schema.test-d.ts error (see comment below).
• eslint clean, npm run build:types emits dist/errors.d.ts.
• All 147 tests pass.

🤖 Generated with Claude Code

[gmaclennan]

Investigation: pre-existing schema.test-d.ts type error

tsc -p tsconfig.json reports:

test/schema.test-d.ts(31,8): error TS2344: Type 'false' does not satisfy the constraint 'true'.

It is unrelated to this PR and predates it — I reproduced it on main (and at the type test's introducing commit 760a3f0 it passed with the current node_modules, so the regression is in source since then, not a dependency bump).

Root cause. Line 31 asserts ExtendsStrict<CategoryOutput, Expected<PresetValue>> — i.e. that our CategoryOutput is still assignable to @comapeo/schema's PresetValue (minus schemaName and with …Ref(s) mapped to strings). The full assignability error:

Property 'geometry' is missing in type '{ name; appliesTo: ("observation" | "track")[]; … }'
  but required in type 'Omit<{ …; geometry: ("point"|"line"|"area"|"vertex"|"relation")[]; … }, …>'

@comapeo/schema's PresetValue has geometry: ("point"|"line"|"area"|…)[]. Commit 45de357 (#12, "change geometry to appliesTo and use CoMapeo doc types") intentionally replaced that with appliesTo: ("observation"|"track")[]. So CategoryOutput no longer mirrors PresetValue 1:1, and the strict-extends assertion is now correctly false.

Why CI is green anyway. Nothing runs this assertion: npm test is node --test (ignores .ts), and npm run build uses tsconfig.npm.json which only includes src/index.js. The .test-d.ts is only checked by tsc -p tsconfig.json, which isn't wired to any script.

Conclusion. The test is stale — it encodes the pre-#12 assumption that categories track presets exactly. It's not a runtime bug. Recommend handling it separately from this PR: either update the assertion to reflect the deliberate geometry → appliesTo divergence (map it in Expected<T>), or drop the CategoryOutput-vs-PresetValue line. The FieldOutput/FieldValue assertion on line 32 still holds.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	custom-error-creator@​1.4.0

View full report