Add encodeImmutable for generated columns

CHANGELOG.md

@@ -4,4 +4,10 @@
 -Created install.sql with working but probably under tested working encode/decode
 
 ## V0.2
--Added spec tests & fixed any failures
+-Added spec tests & fixed any failures
+
+## V0.3
+-Marked pure helpers and decode as IMMUTABLE
+-Kept table-backed encode STABLE (it reads sqids.blocklist)
+-Added sqids.encodeImmutable for generated columns (compiled-in default blocklist, or a TEXT[] argument)
+-Reject negative and NULL numbers instead of hanging in toId

README.md

@@ -32,7 +32,17 @@ Not good for:
 > **Note**
 > 🚧 The `src/install.sql` file is idempotent but destructive. It will `DROP SCHEMA sqids` so be sure you aren't using a schema with that name!
 
-The blocklist is stored in a table. If you need it to somehow be dynamic per-call, you can likely use transactions, but I have not tested it.
+The blocklist is stored in a table. `sqids.encode` reads that table, so Postgres treats it as STABLE. If you need it to somehow be dynamic per-call, you can likely use transactions, but I have not tested it.
+
+`sqids.encodeImmutable` does not read `sqids.blocklist`, which is why it can be used in generated columns. With three arguments it applies the compiled-in default blocklist. Pass a `TEXT[]` as the fourth argument for a static custom list:
+
+```sql
+select sqids.encodeImmutable(array[1, 2, 3], 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789', 0, ARRAY['foo']::text[]);
+```
+
+Table rows only affect `sqids.encode`. `encodeNumbers` with a blocklist argument is the post-shuffle core used by those wrappers — call `encode` / `encodeImmutable` instead of using it in generated columns.
+
+Numbers must be non-negative. Negative values and NULL elements raise an exception (they used to hang the backend).
 
 ### Compatibility
 
@@ -76,6 +86,27 @@ select sqids.encode(array[123, 456, 789], 12); --eVH6til6J03E
 select sqids.decode('eVH6til6J03E'); -- {123,456,789}
 ```
 
+### Generated columns
+
+Use `encodeImmutable` when the ID should be stored as a generated column. `encode` is not allowed there because it reads `sqids.blocklist`.
+
+```sql
+CREATE TABLE orders (
+  id integer PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY,
+  external_id text UNIQUE NOT NULL GENERATED ALWAYS AS (
+    sqids.encodeImmutable(ARRAY[id]::BIGINT[], 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789', 5)
+  ) STORED
+);
+```
+
+A custom static list is a constant array in the expression (not the table):
+
+```sql
+external_id text GENERATED ALWAYS AS (
+  sqids.encodeImmutable(ARRAY[id]::BIGINT[], 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789', 5, ARRAY['foo']::text[])
+) STORED
+```
+
 ## 🧪 Testing
 
 Run the sql files in tests dir to install.
@@ -87,6 +118,7 @@ select sqids.alphabet_test();
 select sqids.blocklist_test();
 select sqids.encoding_test();
 select sqids.minlength_test();
+select sqids.immutable_test();
 ```
 
 ## 📝 License