@vazen-ai/toml 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+Changes to the `@vazen-ai/toml` npm package. Package versions are independent of
+the Vazen TOML file format's `schema_version`.
+
+<!-- Each version repeats the Added, Changed and Fixed headings. -->
+<!-- markdownlint-configure-file { "MD024": { "siblings_only": true } } -->
+
+## [Unreleased]
+
+## [0.2.1] - 2026-10-08
+
+### Fixed
+
+- Fix the npm release workflow, which stopped before publishing 0.2.0. The
+  package code is unchanged from 0.2.0.
+
+## [0.2.0] - 2026-10-06
+
+### Added
+
+- Read PSA tray, case, display and alternate merchandising styles as products
+  with their own packaging dimensions and unit counts.
+- Return structured processing messages alongside the project and source from
+  file readers. PSA messages report recoverable problems; TOML and JSON readers
+  return an empty list. Writers do not store messages in converted files.
+- Include this changelog in the npm package.
+
+### Changed
+
+- Require Effect 4.0.0 or a later 4.x release as a peer dependency. Exported
+  schemas and errors use Effect 4 types, including `SchemaError` in place of
+  `ParseError`. Effect schema decoding uses `Result` instead of `Either`.
+- Rename the PSA records API's `compromises` field to `messages`, and
+  `PsaCompromise` to `PsaMessage`.
+- Reduce temporary allocations when reading PSA cells and writing PSA bytes.
+
+### Fixed
+
+- Match PSA positions using the declared UPC, ID or combined primary key, and
+  preserve unused position identifiers through TOML and JSON round trips. Keep
+  separate PSA product rows distinct when writing.
+- Keep reserved PSA text as text through JSON round trips. Distinguish TOML date
+  kinds when matching product selectors.
+- Read integer PSA codes written as decimals, such as `0.00`.
+- Refuse ambiguous Windows-1252 output that would read back as different UTF-8
+  text. Preserve Windows-1252 bytes `0x80` to `0x9F` on every supported Node.js
+  version.
+- Reject `__proto__` keys when reading or writing TOML and JSON, instead of
+  allowing prototype changes or silently losing data.
+
+## [0.1.0] - 2026-09-29
+
+`@vazen-ai/toml` 0.1.0 is the first release of the package. It reads and writes
+[Vazen TOML](https://toml.vazen.com/) 0.3.0 files, `vazen/spec` and
+`vazen/layout`, as TOML or as JSON. It reads ProSpace PSA files of any version,
+and writes PSA 2017.1.0 to 2024.4.0. Each file reads as the tables of a 0.3.0
+file. A writer writes 0.3.0, or PSA 2024.4.0, unless another version is asked
+for.
+
+```sh
+npm install @vazen-ai/toml
+```
+
+### What reading does not check
+
+Reading checks the shape of a file. It does not check the specification's rules
+of a whole file, nor its spatial rules. A project read from a PSA file drops
+what the records reader lists as compromises, such as a cell its column could
+not read; `decodePsaDataFromPsaFile` shows them.
+[The package README](https://github.com/vazen-ai/toml/blob/main/typescript/README.md)
+says what each function reads and writes, and
+[the PSA README](https://github.com/vazen-ai/toml/blob/main/typescript/src/psa/README.md)
+says which values the PSA reader loses and which the writer keeps.
+
+### Requirements
+
+The package is ESM only, for Node.js 24 or later. It needs Effect 3.14.8 or a
+later 3.x release as a peer dependency. This release was published by hand and
+carries no provenance.

package/README.md

@@ -1,20 +1,23 @@
 # @vazen-ai/toml
 
-`@vazen-ai/toml` 0.1.0 reads and writes [Vazen TOML](https://toml.vazen.com/)
-0.3.0 files, `vazen/spec` and `vazen/layout`, as TOML or as JSON. It reads
-ProSpace PSA files of any version, and writes the versions `PsaVersion` lists,
-2017.1.0 to 2024.4.0. Each file reads as the tables of a 0.3.0 file. A writer
-writes 0.3.0, or PSA 2024.4.0, unless another version is asked for.
+`@vazen-ai/toml` reads and writes [Vazen TOML](https://toml.vazen.com/) 0.3.0
+files, `vazen/spec` and `vazen/layout`, as TOML or as JSON. It reads ProSpace
+PSA files of any version, and writes the versions `PsaVersion` lists, 2017.1.0
+to 2024.4.0. Each file reads as the tables of a 0.3.0 file. A writer writes
+0.3.0, or PSA 2024.4.0, unless another version is asked for.
 [Reading and writing](#reading-and-writing) says what each function reads and
 writes, and what reading does not check.
 
+The [changelog](CHANGELOG.md) records package changes separately from the file
+format's versions.
+
 ```js
 import {
   decodeVazenProjectFromTomlFile,
   encodeJsonFileFromVazenProject,
 } from '@vazen-ai/toml';
 
-const { project, source } =
+const { project, source, messages } =
   decodeVazenProjectFromTomlFile(`schema = "vazen/spec"
 schema_version = "0.3.0"
 
@@ -36,6 +39,8 @@ console.log(project.fixtures[0].equipment[0].sites[0].facings.wide);
 // 3
 console.log(source);
 // { declaredVersion: '0.3.0', format: 'vazen-toml' }
+console.log(messages);
+// []
 console.log(encodeJsonFileFromVazenProject({ project }).includes('"wide": 3'));
 // true
 ```
@@ -46,10 +51,16 @@ A project is the tables of a 0.3.0 file, `VazenTomlProjectV0_3_0`: `products`
 and `fixtures`, each fixture's `equipment`, and each piece of equipment's
 `sites`. When the file gives no value for a key, the key is absent. Keys the
 specification does not define sit beside the standard keys, as in the file. A
-reader returns the file's format and declared version as `source`, beside the
-project. The source is not part of the project, because a writer writes the
-project alone. Reading checks the shape of the file. It does not check the
-specification's rules of a whole file, nor its spatial rules.
+reader returns `{ project, source, messages }`. The source gives the file's
+format and declared version. The messages are structured findings from reading
+or processing the project, with a `_tag` identifying each kind and details such
+as affected records and columns. An empty list means none were reported. Writers
+write the project alone, so these messages are not stored in converted files.
+
+Readers return data that satisfies the project schema. This checks field types
+and allowed values, not full planogram validity or spatial rules. The schemas
+refuse an own `__proto__` key anywhere in a project, when reading or writing.
+This keeps attribute keys safe to copy between JavaScript objects.
 
 ## JSON
 
@@ -57,18 +68,41 @@ The tables also read and write as JSON, in a `.vazen.json` file. The JSON has
 the same keys and the same values. JSON has no date, so the JSON writer writes a
 date as text, such as `"2026-09-27T09:30:00.000Z"`, `"2026-09-27"` or
 `"09:30:00.000"`. The JSON reader reads text in exactly that form as a date, but
-only in an attribute or a product selector. JSON cannot hold `nan` or `inf`, so
-the JSON writer refuses them. The JSON reader refuses an integer beyond
-JavaScript's safe range, as the TOML reader does.
+only in an attribute or a product selector. Text under a `_psa__` key stays
+text, since it holds a PSA cell, and so does a selector's text under a product's
+standard key, such as `name`, since the product's is text. So a `label` of
+`"2026-09-27"` and a `label` of the date `2026-09-27` both read back as the
+date. A selector for the text then matches both products, and the PSA writer
+refuses it. JSON cannot hold `nan` or `inf`, so the JSON writer refuses them.
+The JSON reader refuses an integer beyond JavaScript's safe range, as the TOML
+reader does.
 
 ## PSA files
 
 A PSA file reads as the tables of a 0.3.0 layout. Each planogram is a fixture,
-each fixture row is its equipment, and each position is a site. Every length is
-in millimetres. A value with a standard key takes that key. Every other value
-the file gives becomes a `_psa__` key on its object, unless the column's default
-already implies it. So the project writes back as the same PSA records, also
-after a trip through TOML or JSON.
+each fixture row is its equipment, and each position is a site. A product that a
+position places as a tray, a case, a display or an alternate also reads as one
+more product for each of those styles, as the specification asks. Each one has
+the style as its `form`, the style's dimensions, and the number of units it
+holds as `_vazen__unit_count`. When written, they go back onto the same PSA
+product row. Every length is in millimetres. A value with a standard key takes
+that key. Every other value the file gives becomes a `_psa__` key on its object,
+unless the column's default already implies it. With no reported messages, the
+project writes back as the same PSA records, also after a trip through TOML or
+JSON.
+
+The PSA bridge matches products using the project's primary key: UPC alone, ID
+alone, or the exact pair for Both. An absent primary-key cell defaults to UPC.
+Identifier text is compared exactly, and a missing component compares as empty.
+Both may have one empty component; each placed product and position must have at
+least one identifier. Duplicate primary keys and positions with no match are
+refused. There is no fallback to the secondary identifier.
+
+When a position's unused identifier differs from its product's, its site keeps
+the original cell in `_psa__id` or `_psa__upc`; an empty string means a blank
+cell. These attributes survive TOML and JSON and write back to the position. An
+export is refused if an edit makes them conflict with the selected product under
+the current primary key.
 
 ```js
 import { readFileSync, writeFileSync } from 'node:fs';
@@ -86,6 +120,9 @@ writeFileSync(
 );
 ```
 
+[Read and convert ProSpace PSA planogram files](https://toml.vazen.com/psa)
+shows each conversion with a made-up PSA file to try.
+
 ## Reading and writing
 
 Each format has a pair of file functions. `decodeVazenProjectFromTomlFile` and
@@ -94,25 +131,25 @@ Each format has a pair of file functions. `decodeVazenProjectFromTomlFile` and
 write JSON text. `decodeVazenProjectFromPsaFile` and
 `encodePsaFileFromVazenProject` read and write PSA bytes. The TOML and JSON
 readers take the versions `VazenVersion` lists. The PSA reader takes a file of
-any version. A project read from a PSA file drops what the records reader lists
-in `compromises`, such as a cell its column could not read.
-`decodePsaDataFromPsaFile` shows them. The TOML and JSON writers write 0.3.0.
-The PSA writer writes 2024.4.0. The `version` option names another version that
-`VazenVersion` or `PsaVersion` lists:
+any version on a best-effort basis. Recoverable problems, such as an unreadable
+cell treated as empty or an unfamiliar row width, are reported in `messages`.
+Reading fails when it cannot produce a project that satisfies the schema. The
+TOML and JSON writers write 0.3.0. The PSA writer writes 2024.4.0. The `version`
+option names another version that `VazenVersion` or `PsaVersion` lists:
 `encodePsaFileFromVazenProject({ project, version: '2017.2.0' })`. A writer
 refuses a project that a reader would refuse as a file. The PSA writer also
 refuses a value that a column of the named version cannot hold. Each function
-throws a `ParseError` saying what it could not read or write.
+throws a `SchemaError` saying what it could not read or write.
 
 The Effect schemas behind the file functions are exported for a caller who wants
-an `Either` or an `Effect`: `VazenProjectFromTomlText`,
+a `Result` or an `Effect`: `VazenProjectFromTomlText`,
 `VazenProjectFromJsonText`, `VazenProjectFromPsaBytes`,
 `VazenProjectFromPsaText` and `VazenProjectFromPsaData`. Each schema reads a
 file into `VazenProject`. In a `VazenProject`, an optional value is an Effect
 `Option`, the keys the specification does not define live in each object's
-`attributes`, and `source` is part of the project. So the PSA schemas write the
-version of the PSA file the project came from, when that version can hold the
-project.
+`attributes`, and `source` and `messages` are part of the project. So the PSA
+schemas write the version of the PSA file the project came from, when that
+version can hold the project.
 
 The functions above read a file as a project. To edit the columns of a PSA file,
 read its records instead. `decodePsaDataFromPsaFile` returns `PsaData`, the rows
@@ -121,7 +158,7 @@ file.
 [The PSA README](https://github.com/vazen-ai/toml/blob/main/typescript/src/psa/README.md)
 says which values the reader loses and which values the writer keeps.
 
-The package is ESM only, for Node.js 24 or later. It needs Effect 3.14.8 or a
-later 3.x release as a peer dependency. To work on the package, run `npm ci`
+The package is ESM only, for Node.js 24 or later. It needs Effect 4.0.0 or a
+later 4.x release as a peer dependency. To work on the package, run `npm ci`
 then `npm run verify` here. Licensing is in
 [LICENSING.md](https://github.com/vazen-ai/toml/blob/main/LICENSING.md).