@lunora/sql-store 1.0.0-alpha.3 → 1.0.0-alpha.30

package/dist/dialect.d.mts

@@ -46,9 +46,19 @@ interface SqlDialect {
     real: string;
     text: string;
   };
-  /** Map a stored value back to its JS form, by effective validator `kind` (inverse of `encode`). */
+  /**
+  * Map a stored value back to its JS form, by effective validator `kind`
+  * (inverse of `encode`). NOTE: currently **unused** by the store core, which
+  * hard-codes `sqliteDecode` in `decodeGlobalRow` on every engine. Kept on the
+  * seam for a future engine-native codec; an override here does not run today.
+  */
   decode: (value: unknown, kind: string | undefined) => unknown;
-  /** Map a JS value to its bound storage form (boolean→1/0, bigint→string, object→JSON on SQLite; mostly native on PG). */
+  /**
+  * Map a JS value to its bound storage form (boolean→1/0, bigint→string,
+  * object→JSON on SQLite). NOTE: currently **unused** by the store core, which
+  * hard-codes `sqliteEncode` as `serializeColumnValue` on every engine. Kept on
+  * the seam for a future engine-native codec; an override here does not run today.
+  */
   encode: (value: unknown) => unknown;
   /** The framework columns every global table carries — the `id` primary key and `_creationTime` — as `{ name, type }` so the DDL builder can quote each name through the engine's dialect. */
   frameworkColumns: () => ReadonlyArray<{

package/dist/dialect.d.ts

@@ -46,9 +46,19 @@ interface SqlDialect {
     real: string;
     text: string;
   };
-  /** Map a stored value back to its JS form, by effective validator `kind` (inverse of `encode`). */
+  /**
+  * Map a stored value back to its JS form, by effective validator `kind`
+  * (inverse of `encode`). NOTE: currently **unused** by the store core, which
+  * hard-codes `sqliteDecode` in `decodeGlobalRow` on every engine. Kept on the
+  * seam for a future engine-native codec; an override here does not run today.
+  */
   decode: (value: unknown, kind: string | undefined) => unknown;
-  /** Map a JS value to its bound storage form (boolean→1/0, bigint→string, object→JSON on SQLite; mostly native on PG). */
+  /**
+  * Map a JS value to its bound storage form (boolean→1/0, bigint→string,
+  * object→JSON on SQLite). NOTE: currently **unused** by the store core, which
+  * hard-codes `sqliteEncode` as `serializeColumnValue` on every engine. Kept on
+  * the seam for a future engine-native codec; an override here does not run today.
+  */
   encode: (value: unknown) => unknown;
   /** The framework columns every global table carries — the `id` primary key and `_creationTime` — as `{ name, type }` so the DDL builder can quote each name through the engine's dialect. */
   frameworkColumns: () => ReadonlyArray<{

package/dist/index.d.mts

@@ -168,6 +168,12 @@ declare const effectiveColumnKind: (validator: ValidatorLike) => string | undefi
 * - `object`/`array`/`record`: JSON string → parsed value.
 * - `union`/`any`: parsed back only when the stored string is a JSON non-scalar
 *   (a scalar union member round-trips through SQLite's native column type).
+*   CAVEAT: a union/any member is stored verbatim by {@link sqliteEncode}, so a
+*   legitimate *string* value that itself looks like JSON (`'{"a":1}'`, `'[1,2]'`)
+*   is ambiguous on read and decodes back to the parsed object/array, not the
+*   original string. This is inherent to sharing one TEXT column between a string
+*   and an object member; disambiguating would require a breaking storage-format
+*   change (tagging encoded non-scalars), so it is documented rather than fixed.
 * - everything else (string/number/date/timestamp/id/literal): verbatim.
 */
 declare const sqliteDecode: (raw: unknown, kind: string | undefined) => unknown;

package/dist/index.d.ts

@@ -168,6 +168,12 @@ declare const effectiveColumnKind: (validator: ValidatorLike) => string | undefi
 * - `object`/`array`/`record`: JSON string → parsed value.
 * - `union`/`any`: parsed back only when the stored string is a JSON non-scalar
 *   (a scalar union member round-trips through SQLite's native column type).
+*   CAVEAT: a union/any member is stored verbatim by {@link sqliteEncode}, so a
+*   legitimate *string* value that itself looks like JSON (`'{"a":1}'`, `'[1,2]'`)
+*   is ambiguous on read and decodes back to the parsed object/array, not the
+*   original string. This is inherent to sharing one TEXT column between a string
+*   and an object member; disambiguating would require a breaking storage-format
+*   change (tagging encoded non-scalars), so it is documented rather than fixed.
 * - everything else (string/number/date/timestamp/id/literal): verbatim.
 */
 declare const sqliteDecode: (raw: unknown, kind: string | undefined) => unknown;

package/dist/index.mjs

@@ -1,2 +1,2 @@
-export { createSqlCtxDb, decodeGlobalRow, readSqlCdcChanges, runSqlAggregateMigrations, runSqlCdcMigration, runSqlGlobalTableMigrations, runSqlRankMigrations, runSqlSearchMigrations, trimSqlCdcChanges } from './packem_shared/createSqlCtxDb-CQFYyQLP.mjs';
-export { decodeBigint, effectiveColumnKind, sqliteDecode, sqliteEncode, tryJsonParse } from './packem_shared/sqliteEncode-Dedu92k4.mjs';
+export { createSqlCtxDb, decodeGlobalRow, readSqlCdcChanges, runSqlAggregateMigrations, runSqlCdcMigration, runSqlGlobalTableMigrations, runSqlRankMigrations, runSqlSearchMigrations, trimSqlCdcChanges } from './packem_shared/createSqlCtxDb-KdluzmSA.mjs';
+export { decodeBigint, effectiveColumnKind, sqliteDecode, sqliteEncode, tryJsonParse } from './packem_shared/decodeBigint-Dedu92k4.mjs';