@syncular/typegen 0.15.44 → 0.15.46

package/README.md

@@ -1,7 +1,7 @@
 # @syncular/typegen
 
 SQL migrations + one manifest → neutral schema IR (JSON) → generated TS
-module (REVISE B5). This file is the authoritative contract for the three
+module. This file is the authoritative contract for the three
 tool-level formats: the manifest, the IR, and the SQL subset. Wire-protocol
 semantics (column types, scope patterns, schema-version gating) live in
 [`../../docs/SPEC.md`](../../docs/SPEC.md) §2.4, §3.1, §1.5 — this document never
@@ -374,8 +374,9 @@ The emitted `*.generated.ts` module:
   (requested scopes), plus an `SParams` interface when the template has
   `{param}` placeholders.
 
-**Lint/freshness split**: `*.generated.ts` is excluded from biome (see
-`biome.json`) — hand-format rules on machine output only create churn.
+**Lint/freshness split**: `*.generated.ts` is excluded from oxlint and oxfmt
+(see `.oxlintrc.json` / `.oxfmtrc.json`) — hand-format rules on machine
+output only create churn.
 Freshness and migration-history integrity are enforced instead by `syncular
 generate --check`, which is byte-exact and refuses locked-history drift; the
 generated fixture is still typechecked by `tsc` and exercised by tests.
@@ -450,8 +451,8 @@ revision-1 structured frontend: authoritative typed inputs, explicit
 `when(...)` conjuncts, atomic optional groups, imported hygienic predicates,
 inferred scope dependencies, explicit sync coverage, complete sort profiles,
 bounded limits, and inferred identity. Its complete normative definition is
-[`../../docs/SYQL.md`](../../docs/SYQL.md); the rationale and implementation
-record are [`../../docs/rfcs/0004-syql-language.md`](../../docs/rfcs/0004-syql-language.md).
+[`../../docs/SYQL.md`](../../docs/SYQL.md). Both frontends produce the same
+deterministic QueryIR consumed by every language emitter.
 
 Tooling: `syncular generate --print <name>` prints every selected checked
 statement and bind, `syncular fmt` is the semantic-preserving canonical

package/dist/emit-queries.js

@@ -272,6 +272,7 @@ function emitSyqlQuery(query, hash) {
         lines.push(`  sqlFor: (params: ${Params}) => ${query.name}Select(params).sql,`);
     }
     lines.push(`  tables: ${query.name}Tables,`);
+    lines.push(`  resultColumns: [${query.columns.map((column) => `{ name: ${quote(column.langName)}, type: ${quote(column.type)}, nullable: ${column.nullable} }`).join(', ')}],`);
     const reactiveUsesParams = query.reactive.dependencies.some((dependency) => dependency.scopes.some((scope) => scope.params.length > 0));
     lines.push(`  dependencies: (${reactiveUsesParams ? 'params' : ''}) => [`);
     for (const dependency of query.reactive.dependencies) {
@@ -359,6 +360,7 @@ function emitQuery(query, hash) {
     lines.push(`  sql: ${sqlConst},`);
     lines.push(`  mapRow: ${query.name}MapRow,`);
     lines.push(`  tables: ${query.name}Tables,`);
+    lines.push(`  resultColumns: [${query.columns.map((column) => `{ name: ${quote(column.langName)}, type: ${quote(column.type)}, nullable: ${column.nullable} }`).join(', ')}],`);
     const reactiveUsesParams = query.reactive.dependencies.some((dependency) => dependency.scopes.some((scope) => scope.params.length > 0));
     lines.push(`  dependencies: (${reactiveUsesParams ? 'params' : ''}) => [`);
     for (const dependency of query.reactive.dependencies) {
@@ -472,6 +474,7 @@ export function emitQueriesModule(queries, hash, irVersion) {
         '  readonly sql: string;',
         '  readonly mapRow: (row: Readonly<Record<string, unknown>>) => Row;',
         '  readonly tables: readonly string[];',
+        '  readonly resultColumns: readonly QueryResultColumn[];',
         '  readonly bind: (params: Params) => readonly QueryValue[];',
         '  readonly sqlFor?: (params: Params) => string;',
         '  readonly dependencies: (params: Params) => readonly QueryDependency[];',
@@ -486,6 +489,12 @@ export function emitQueriesModule(queries, hash, irVersion) {
         '  readonly scopeKeys?: readonly string[];',
         '}',
         '',
+        'export interface QueryResultColumn {',
+        '  readonly name: string;',
+        "  readonly type: 'string' | 'integer' | 'float' | 'boolean' | 'json' | 'bytes' | 'blob_ref' | 'crdt';",
+        '  readonly nullable: boolean;',
+        '}',
+        '',
         'export interface WindowCoverage {',
         '  readonly base: {',
         '    readonly table: string;',

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * @syncular/typegen — SQL migrations + syncular.json → neutral schema
- * IR (JSON) → generated TS module (REVISE B5). Dependency-free; the CLI
+ * IR (JSON) → generated TS module. Dependency-free; the CLI
  * lives in `src/cli.ts` (bin `syncular`).
  */
 export * from './emit.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 /**
  * @syncular/typegen — SQL migrations + syncular.json → neutral schema
- * IR (JSON) → generated TS module (REVISE B5). Dependency-free; the CLI
+ * IR (JSON) → generated TS module. Dependency-free; the CLI
  * lives in `src/cli.ts` (bin `syncular`).
  */
 export * from './emit.js';

package/dist/ir.d.ts

@@ -27,7 +27,7 @@ export interface IrScope {
  * One local secondary index declared by a `CREATE [UNIQUE] INDEX` migration.
  * Applied on BOTH sides: the client materializes it in its local SQLite, and
  * the server creates it on the relational per-app row table
- * (DESIGN-relational-server-storage.md "user indexes"; the sync read path
+ * (the server-storage user-index contract; the sync read path
  * itself still uses the scope inverted-index). `columns` preserves declared
  * order (a compound index is order-sensitive). Index order within a table is
  * declaration order.

package/dist/ir.js

@@ -1,5 +1,5 @@
 /**
- * Neutral schema IR (REVISE B5).
+ * Neutral schema IR.
  *
  * The IR is a versioned, language-neutral JSON document: tables with the
  * SPEC §2.4 column types (+ nullability + primary key), scope patterns

package/dist/lower.js

@@ -1,5 +1,5 @@
 /**
- * Projection lowering (DESIGN-queries.md §5): rewrite a query's top-level
+ * Projection lowering: rewrite a query's top-level
  * SELECT list so the runtime result keys ARE the language-facing names —
  * `select created_at from todos` lowers to
  * `select created_at as createdAt from todos` under camelCase naming, so

package/dist/manifest.js

@@ -1,5 +1,5 @@
 /**
- * `syncular.json` manifest (REVISE B5) — designed here, minimal but
+ * `syncular.json` manifest: minimal but
  * forward-extensible:
  *
  * ```json

package/dist/naming.d.ts

@@ -8,7 +8,7 @@ export declare function snakeToCamel(name: string): string;
  * small set that breaks generated FUNCTION/const identifiers). */
 export type NamingTarget = 'ts' | 'swift' | 'kotlin' | 'dart' | 'rust';
 export declare function isRustKeyword(name: string): boolean;
-/** Pinned Rust identifier conversion from RFC 0006. */
+/** Pinned Rust identifier conversion. */
 export declare function rustSnakeCase(name: string): string;
 export declare function rustPascalCase(name: string): string;
 export interface RustNameMapping {

package/dist/naming.js

@@ -1,5 +1,5 @@
 /**
- * The pinned naming-map algorithm (DESIGN-queries.md §5, §12): SQL stays
+ * The pinned naming-map algorithm: SQL stays
  * snake_case; emitters render their language's convention. The IR carries
  * SQL-truth names plus a derived, collision-checked map — this module is
  * that derivation.
@@ -259,7 +259,7 @@ const TARGET_KEYWORDS = {
 export function isRustKeyword(name) {
     return TARGET_KEYWORDS.rust.has(name);
 }
-/** Pinned Rust identifier conversion from RFC 0006. */
+/** Pinned Rust identifier conversion. */
 export function rustSnakeCase(name) {
     if (!/^_*[A-Za-z][A-Za-z0-9_]*$/.test(name))
         return name;

package/dist/query-ir.d.ts

@@ -1,5 +1,5 @@
 /**
- * QueryIR serialization (DESIGN-queries.md §1): the frontend-agnostic,
+ * QueryIR serialization: the frontend-agnostic,
  * deterministic JSON form of analyzed queries. This is the golden-fixture
  * format — equivalent inputs in any frontend (`.sql` today, `.syql` later)
  * must produce byte-identical IR JSON, the same trick the wire protocol

package/dist/sql.js

@@ -1,5 +1,5 @@
 /**
- * SQL migration subset parser (REVISE B5).
+ * SQL migration subset parser.
  *
  * Parses exactly the subset v1-style migrations need:
  *
@@ -10,7 +10,7 @@
  * - `DROP INDEX [IF EXISTS] name`
  * - `DROP TABLE [IF EXISTS] name`
  * - `CREATE VIRTUAL TABLE name USING fts5(cols…, content=table,
- *   [tokenize='allowlisted tokenizer'])` (RFC 0005 local projection)
+ *   [tokenize='allowlisted tokenizer'])` (client-local FTS5 projection)
  * - column defs: `name TYPE [PRIMARY KEY] [NOT NULL] [NULL]
  *   [DEFAULT literal]`; `ALTER TABLE … ADD COLUMN` is restricted to nullable
  *   columns because Syncular does not execute SQL-default backfills
@@ -337,7 +337,7 @@ const ALLOWED_FTS_TOKENIZERS = new Set([
     'trigram',
 ]);
 /** Parse the deliberately narrow migration-subset v2 FTS5 form documented in
- * RFC 0005. The virtual table is attached to its owning synced
+ * The virtual table is attached to its owning synced
  * table and is not itself a synced table. */
 function parseCreateVirtualTable(cursor, tables, source, options) {
     cursor.expectWord('TABLE', 'after CREATE VIRTUAL');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/typegen",
-  "version": "0.15.44",
+  "version": "0.15.46",
   "description": "Syncular schema-to-TypeScript type generator and the `syncular` CLI",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -56,9 +56,9 @@
     "!dist/**/*.test.d.ts"
   ],
   "dependencies": {
-    "@syncular/core": "0.15.44"
+    "@syncular/core": "0.15.46"
   },
   "devDependencies": {
-    "@syncular/server": "0.15.44"
+    "@syncular/server": "0.15.46"
   }
 }

package/src/emit-queries.ts

@@ -399,6 +399,9 @@ function emitSyqlQuery(query: AnalyzedQuery, hash: string): string {
     );
   }
   lines.push(`  tables: ${query.name}Tables,`);
+  lines.push(
+    `  resultColumns: [${query.columns.map((column) => `{ name: ${quote(column.langName)}, type: ${quote(column.type)}, nullable: ${column.nullable} }`).join(', ')}],`,
+  );
   const reactiveUsesParams = query.reactive.dependencies.some((dependency) =>
     dependency.scopes.some((scope) => scope.params.length > 0),
   );
@@ -537,6 +540,9 @@ function emitQuery(query: AnalyzedQuery, hash: string): string {
   lines.push(`  sql: ${sqlConst},`);
   lines.push(`  mapRow: ${query.name}MapRow,`);
   lines.push(`  tables: ${query.name}Tables,`);
+  lines.push(
+    `  resultColumns: [${query.columns.map((column) => `{ name: ${quote(column.langName)}, type: ${quote(column.type)}, nullable: ${column.nullable} }`).join(', ')}],`,
+  );
   const reactiveUsesParams = query.reactive.dependencies.some((dependency) =>
     dependency.scopes.some((scope) => scope.params.length > 0),
   );
@@ -683,6 +689,7 @@ export function emitQueriesModule(
       '  readonly sql: string;',
       '  readonly mapRow: (row: Readonly<Record<string, unknown>>) => Row;',
       '  readonly tables: readonly string[];',
+      '  readonly resultColumns: readonly QueryResultColumn[];',
       '  readonly bind: (params: Params) => readonly QueryValue[];',
       '  readonly sqlFor?: (params: Params) => string;',
       '  readonly dependencies: (params: Params) => readonly QueryDependency[];',
@@ -697,6 +704,12 @@ export function emitQueriesModule(
       '  readonly scopeKeys?: readonly string[];',
       '}',
       '',
+      'export interface QueryResultColumn {',
+      '  readonly name: string;',
+      "  readonly type: 'string' | 'integer' | 'float' | 'boolean' | 'json' | 'bytes' | 'blob_ref' | 'crdt';",
+      '  readonly nullable: boolean;',
+      '}',
+      '',
       'export interface WindowCoverage {',
       '  readonly base: {',
       '    readonly table: string;',

package/src/index.ts

@@ -1,6 +1,6 @@
 /**
  * @syncular/typegen — SQL migrations + syncular.json → neutral schema
- * IR (JSON) → generated TS module (REVISE B5). Dependency-free; the CLI
+ * IR (JSON) → generated TS module. Dependency-free; the CLI
  * lives in `src/cli.ts` (bin `syncular`).
  */
 export * from './emit';

package/src/ir.ts

@@ -1,5 +1,5 @@
 /**
- * Neutral schema IR (REVISE B5).
+ * Neutral schema IR.
  *
  * The IR is a versioned, language-neutral JSON document: tables with the
  * SPEC §2.4 column types (+ nullability + primary key), scope patterns
@@ -53,7 +53,7 @@ export interface IrScope {
  * One local secondary index declared by a `CREATE [UNIQUE] INDEX` migration.
  * Applied on BOTH sides: the client materializes it in its local SQLite, and
  * the server creates it on the relational per-app row table
- * (DESIGN-relational-server-storage.md "user indexes"; the sync read path
+ * (the server-storage user-index contract; the sync read path
  * itself still uses the scope inverted-index). `columns` preserves declared
  * order (a compound index is order-sensitive). Index order within a table is
  * declaration order.

package/src/lower.ts

@@ -1,5 +1,5 @@
 /**
- * Projection lowering (DESIGN-queries.md §5): rewrite a query's top-level
+ * Projection lowering: rewrite a query's top-level
  * SELECT list so the runtime result keys ARE the language-facing names —
  * `select created_at from todos` lowers to
  * `select created_at as createdAt from todos` under camelCase naming, so

package/src/manifest.ts

@@ -1,5 +1,5 @@
 /**
- * `syncular.json` manifest (REVISE B5) — designed here, minimal but
+ * `syncular.json` manifest: minimal but
  * forward-extensible:
  *
  * ```json

package/src/naming.ts

@@ -1,5 +1,5 @@
 /**
- * The pinned naming-map algorithm (DESIGN-queries.md §5, §12): SQL stays
+ * The pinned naming-map algorithm: SQL stays
  * snake_case; emitters render their language's convention. The IR carries
  * SQL-truth names plus a derived, collision-checked map — this module is
  * that derivation.
@@ -270,7 +270,7 @@ export function isRustKeyword(name: string): boolean {
   return TARGET_KEYWORDS.rust.has(name);
 }
 
-/** Pinned Rust identifier conversion from RFC 0006. */
+/** Pinned Rust identifier conversion. */
 export function rustSnakeCase(name: string): string {
   if (!/^_*[A-Za-z][A-Za-z0-9_]*$/.test(name)) return name;
   const lead = /^_*/.exec(name)?.[0] ?? '';

package/src/query-ir.ts

@@ -1,5 +1,5 @@
 /**
- * QueryIR serialization (DESIGN-queries.md §1): the frontend-agnostic,
+ * QueryIR serialization: the frontend-agnostic,
  * deterministic JSON form of analyzed queries. This is the golden-fixture
  * format — equivalent inputs in any frontend (`.sql` today, `.syql` later)
  * must produce byte-identical IR JSON, the same trick the wire protocol

package/src/sql.ts

@@ -1,5 +1,5 @@
 /**
- * SQL migration subset parser (REVISE B5).
+ * SQL migration subset parser.
  *
  * Parses exactly the subset v1-style migrations need:
  *
@@ -10,7 +10,7 @@
  * - `DROP INDEX [IF EXISTS] name`
  * - `DROP TABLE [IF EXISTS] name`
  * - `CREATE VIRTUAL TABLE name USING fts5(cols…, content=table,
- *   [tokenize='allowlisted tokenizer'])` (RFC 0005 local projection)
+ *   [tokenize='allowlisted tokenizer'])` (client-local FTS5 projection)
  * - column defs: `name TYPE [PRIMARY KEY] [NOT NULL] [NULL]
  *   [DEFAULT literal]`; `ALTER TABLE … ADD COLUMN` is restricted to nullable
  *   columns because Syncular does not execute SQL-default backfills
@@ -434,7 +434,7 @@ const ALLOWED_FTS_TOKENIZERS = new Set([
 ]);
 
 /** Parse the deliberately narrow migration-subset v2 FTS5 form documented in
- * RFC 0005. The virtual table is attached to its owning synced
+ * The virtual table is attached to its owning synced
  * table and is not itself a synced table. */
 function parseCreateVirtualTable(
   cursor: Cursor,