@kequtech/tenon-orm 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.4.5
+
+- Preserve generated enum and enum-domain label unions when unrelated codecs change, including
+  Date and bigint decoding. Custom enum decoders retain their declared output types; unidentified
+  decoders still warn and generate `unknown`. Enum write inputs retain catalog choices.
+- Require pgclear `^0.3.3` for per-type default-decoder metadata and dynamic notification
+  subscriptions. Native listeners can add and remove channels on one dedicated connection; see
+  [notifications](docs/connections.md#listen-for-notifications) for ownership and recovery.
+
 ## 0.4.4
 
 - Pass the shared `TenonConfig` directly to `createTenon`, including its connection, codecs, and

package/dist/generation/render.js

@@ -6,12 +6,13 @@ function columnTypes(column, codecs, path, warn) {
         warn(`Column ${path} uses a custom decoder without a known TypeScript representation; generated as unknown.`);
         read = 'unknown';
     }
-    const choices = column.choices?.map((choice) => JSON.stringify(choice)).join(' | ') || 'never';
-    if (column.typeKind === 'e' && codecs === defaultCodecs && read === 'string')
-        read = choices;
     let write = defaultCodecs.typescript(oid);
-    if (column.typeKind === 'e')
+    if (column.typeKind === 'e') {
+        const choices = column.choices?.map((choice) => JSON.stringify(choice)).join(' | ') || 'never';
+        if (read === 'string' && codecs.isDefaultDecoder(oid))
+            read = choices;
         write = choices;
+    }
     if (write === 'unknown' || write.startsWith('PgArray<'))
         write = 'string';
     if ([20, 1700].includes(oid))

package/docs/connections.md

@@ -181,20 +181,29 @@ During application startup, pass a validated PostgreSQL URI (`connection` below)
 import { listen } from '@kequtech/pgclear';
 
 const listener = await listen(connection, {
-  channels: ['users_changed'],
+  channels: [],
   onNotification: ({ payload }) => console.log(payload),
   reconnect: true,
 });
+// Membership can change on this same connection. Await server registration:
+await listener.subscribe('users_changed');
+// When the channel is no longer needed:
+await listener.unsubscribe('users_changed');
 // At shutdown:
 await listener.close();
 ```
 
-A listener has a separate lifetime and is not closed by `db.close()`. Notifications are not replayed
-after a disconnection; the application owns its recovery policy.
+A listener has a separate lifetime and is not closed by `db.close()`. Subscription changes share its
+dedicated connection; reconnect restores the last acknowledged channel set. Subscriptions are set
+operations: repeated subscribes do not add reference counts. Applications own subscriber counts,
+authorization, and routing. Notifications are not replayed after a disconnection; use the listener's
+status/generation changes to detect a possible gap and reconcile persistent state. See
+[pgclear's notification guide](https://github.com/kequtech/pgclear/blob/main/docs/notifications.md)
+for deadlines, cancellation, and changes queued during reconnect.
 
 ## Update the driver
 
-Tenon depends on `@kequtech/pgclear: ^0.3.0`, which permits compatible 0.3.x patch updates. With npm:
+Tenon depends on `@kequtech/pgclear: ^0.3.3`, which permits compatible 0.3.x patch updates. With npm:
 
 ```sh
 npm update @kequtech/pgclear

package/docs/reference.md

@@ -44,7 +44,7 @@ handling, timeout bounds, and lifecycle examples. Runtime `search_path` is indep
 
 ### Driver updates
 
-The dependency range is `@kequtech/pgclear: ^0.3.0`. Compatible patches may be updated independently;
+The dependency range is `@kequtech/pgclear: ^0.3.3`. Compatible patches may be updated independently;
 see [driver updates](connections.md#update-the-driver). Tenon re-exports `builtin`, `json`, `param`,
 `defaultCodecs`, and `createTemporalCodecs`, with the driver's `Codec`, `CodecRegistry`, `Parameter`,
 `PgArray`, `TemporalConstructors`, and `TemporalInput` types.

package/docs/schema-types.md

@@ -131,22 +131,22 @@ well typed; PostgreSQL still enforces constraints.
 These are the default driver representations. SQL NULL is `null`; nullable generated columns add
 null to their type. Input encoding and output decoding are separate choices.
 
-| PostgreSQL value                                            | Default read                                           | Plain write input                                             |
-| ----------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------- |
-| smallint, integer, serial, oid                              | `number`                                               | `number`                                                      |
-| bigint, bigserial, `count(*)`                               | Exact `string`                                         | Exact string or bigint                                        |
-| numeric/decimal                                             | `string`                                               | String or bigint                                              |
-| real, double precision                                      | `number`                                               | Finite number                                                 |
-| boolean                                                     | `boolean`                                              | Boolean                                                       |
-| text, UUID, other textual types                             | `string`                                               | String                                                        |
-| enum                                                        | Catalog label union in default-registry generated rows | Label union                                                   |
-| date, timestamp, timestamptz                                | `string`                                               | String, Date, or supported Temporal value                     |
-| time, interval                                              | `string`                                               | String or supported Temporal value                            |
-| timetz                                                      | `string`                                               | String                                                        |
-| json/jsonb                                                  | `unknown`                                              | Encoded JSON string; use `json(value)` for a parameter        |
-| bytea                                                       | `Uint8Array`                                           | Uint8Array                                                    |
-| Supported built-in arrays                                   | Recursive readonly `PgArray<T>`                        | Encoded PostgreSQL array text; use `param` for an array value |
-| Unrecognized types and dynamic enum/domain/extension arrays | Wire-text `string`                                     | Encoded string or explicit parameter                          |
+| PostgreSQL value                                            | Default read                                         | Plain write input                                             |
+| ----------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------- |
+| smallint, integer, serial, oid                              | `number`                                             | `number`                                                      |
+| bigint, bigserial, `count(*)`                               | Exact `string`                                       | Exact string or bigint                                        |
+| numeric/decimal                                             | `string`                                             | String or bigint                                              |
+| real, double precision                                      | `number`                                             | Finite number                                                 |
+| boolean                                                     | `boolean`                                            | Boolean                                                       |
+| text, UUID, other textual types                             | `string`                                             | String                                                        |
+| enum                                                        | Catalog label union when its decoder remains default | Label union                                                   |
+| date, timestamp, timestamptz                                | `string`                                             | String, Date, or supported Temporal value                     |
+| time, interval                                              | `string`                                             | String or supported Temporal value                            |
+| timetz                                                      | `string`                                             | String                                                        |
+| json/jsonb                                                  | `unknown`                                            | Encoded JSON string; use `json(value)` for a parameter        |
+| bytea                                                       | `Uint8Array`                                         | Uint8Array                                                    |
+| Supported built-in arrays                                   | Recursive readonly `PgArray<T>`                      | Encoded PostgreSQL array text; use `param` for an array value |
+| Unrecognized types and dynamic enum/domain/extension arrays | Wire-text `string`                                   | Encoded string or explicit parameter                          |
 
 Generated inputs conservatively describe column-compatible representations; an explicit `Parameter`
 is accepted for every writable column. PostgreSQL checks ranges and text formats. Plain undefined,
@@ -200,8 +200,11 @@ configuration needs the corresponding Temporal library declarations.
 
 A custom text codec can declare `text.typescript` to describe its non-NULL output. Generation and
 checking consume the registry's metadata. An unidentified decoder warns and becomes `unknown`;
-a declared representation is trusted, not runtime validation. Under a custom registry, enum output
-may remain string because a decoder can transform labels; enum write inputs retain catalog choices.
+a declared representation is trusted, not runtime validation. Generated enum rows retain catalog label
+unions when that enum's decoder remains default, including when unrelated Date, bigint, or other
+codecs change. A custom enum decoder uses its own declared output type, or `unknown` with a warning
+when unidentified; declaring `string` does not establish that it preserves catalog labels. Enum write
+inputs retain catalog choices regardless of the output decoder.
 
 Place the registry in shared `connection.codecs` so runtime, CLI generation, inspection, and source
 checking use it consistently. Programmatic inspection/checking inherit `connection.codecs` too. Relative type-import

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kequtech/tenon-orm",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "license": "ISC",
   "type": "module",
   "description": "A PostgreSQL ORM designed for coding agents, with explicit SQL, typed queries, and migrations",
@@ -71,7 +71,7 @@
     "printWidth": 100
   },
   "dependencies": {
-    "@kequtech/pgclear": "^0.3.0",
+    "@kequtech/pgclear": "^0.3.3",
     "typescript": "~6.0.2"
   }
 }