@atscript/db-sql-tools 0.1.139 → 0.1.141

package/dist/index.cjs

@@ -642,9 +642,12 @@ function viewAggExpr(dialect, c, resolveFieldRef) {
 * Builds a CREATE VIEW statement from a view plan and column mappings.
 *
 * Joins render in declaration order — `JOIN` (inner, the default) or
-* `LEFT JOIN` for `kind: "left"`. Column mappings carry PHYSICAL source
-* names; `resolveFieldRef` renders predicate refs (join ON, WHERE, HAVING
-* fallbacks) as `"table"."column"`.
+* `LEFT JOIN` for `kind: "left"`; a `@db.alias` target renders as
+* `JOIN "table" AS "Alias"` and is addressed by the alias everywhere else
+* (since 0.1.141). Column mappings carry PHYSICAL source names (the alias
+* name for an aliased join); `resolveFieldRef` renders predicate refs (join
+* ON, WHERE, HAVING fallbacks) as `"table"."column"`. The entry table and a
+* join target may be views.
 */
 function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
 	const selectCols = columns.map((c) => {
@@ -654,7 +657,8 @@ function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
 	for (const join of plan.joins) {
 		const onClause = queryNodeToSql(join.condition, resolveFieldRef);
 		const keyword = join.kind === "left" ? "LEFT JOIN" : "JOIN";
-		sql += ` ${keyword} ${dialect.quoteIdentifier(join.targetTable)} ON ${onClause}`;
+		const target = join.scope === join.targetTable ? dialect.quoteIdentifier(join.targetTable) : `${dialect.quoteIdentifier(join.targetTable)} AS ${dialect.quoteIdentifier(join.scope)}`;
+		sql += ` ${keyword} ${target} ON ${onClause}`;
 	}
 	if (plan.filter) {
 		const whereClause = queryNodeToSql(plan.filter, resolveFieldRef);
@@ -762,16 +766,18 @@ function buildSelect(dialect, table, where, controls) {
 */
 const SQL_DEFAULT = Symbol("SQL_DEFAULT");
 /**
-* The columns a full replace assigns on a SQL adapter: every non-ignored
-* descriptor (the same set `CREATE TABLE` emits) except the primary key —
-* the row is matched by the filter, and an omitted PK must never be nulled
-* or re-defaulted. Static value defaults are filled SDK-side before the
-* adapter sees the row, so only native function defaults are flagged.
+* The columns a full replace assigns on a SQL adapter: the readable's
+* `storedDescriptors` (non-ignored, not derived — a generated column is
+* never assigned) except the primary key — the row is matched by the filter,
+* and an omitted PK must never be nulled or re-defaulted. Static value
+* defaults are filled SDK-side before the adapter sees the row, so only
+* native function defaults are flagged. Ignored and derived descriptors in
+* `fields` are skipped, so `fieldDescriptors` works too.
 */
 function replaceColumnsFor(fields, nativeFns) {
 	const out = [];
 	for (const fd of fields) {
-		if (fd.ignored || fd.isPrimaryKey) continue;
+		if (fd.ignored || fd.isPrimaryKey || fd.derived) continue;
 		const def = fd.defaultValue;
 		out.push({
 			name: fd.physicalName,
@@ -868,6 +874,22 @@ function buildDelete(dialect, table, where, limit) {
 	});
 }
 /**
+* The expression a `@db.column.derived` column is generated from: the
+* dialect's typed {@link SqlDialect.jsonExtract} over the (unqualified,
+* quoted) JSON source column — the same extraction a view's JSON leaf uses,
+* so both read a leaf identically. Parameter-free by contract; rendered in
+* `CREATE TABLE` / `ADD COLUMN` as `GENERATED ALWAYS AS (<expr>)`.
+*
+* @throws when `field` is not derived or the dialect has no `jsonExtract`.
+* @since 0.1.141
+*/
+function derivedColumnExpr(dialect, field) {
+	const derived = field.derived;
+	if (!derived) throw new Error(`Column "${field.physicalName}" is not a derived column`);
+	if (!dialect.jsonExtract) throw new Error(`Derived column "${field.physicalName}": JSON extraction is not supported by this adapter`);
+	return dialect.jsonExtract(dialect.quoteIdentifier(derived.sourceColumn), derived.jsonPath, derived.type);
+}
+/**
 * Builds a column projection (SELECT clause fields).
 */
 function buildProjection(dialect, select) {
@@ -926,6 +948,7 @@ exports.buildWhere = buildWhere;
 exports.createFilterVisitor = createFilterVisitor;
 exports.defaultValueForType = defaultValueForType;
 exports.defaultValueToSqlLiteral = defaultValueToSqlLiteral;
+exports.derivedColumnExpr = derivedColumnExpr;
 exports.fillReplacePayload = fillReplacePayload;
 exports.finalizeParams = finalizeParams;
 exports.geoWindowFromControls = geoWindowFromControls;

package/dist/index.d.cts

@@ -182,9 +182,12 @@ declare function renameGeoDistance(row: Record<string, unknown>): Record<string,
  * Builds a CREATE VIEW statement from a view plan and column mappings.
  *
  * Joins render in declaration order — `JOIN` (inner, the default) or
- * `LEFT JOIN` for `kind: "left"`. Column mappings carry PHYSICAL source
- * names; `resolveFieldRef` renders predicate refs (join ON, WHERE, HAVING
- * fallbacks) as `"table"."column"`.
+ * `LEFT JOIN` for `kind: "left"`; a `@db.alias` target renders as
+ * `JOIN "table" AS "Alias"` and is addressed by the alias everywhere else
+ * (since 0.1.141). Column mappings carry PHYSICAL source names (the alias
+ * name for an aliased join); `resolveFieldRef` renders predicate refs (join
+ * ON, WHERE, HAVING fallbacks) as `"table"."column"`. The entry table and a
+ * join target may be views.
  */
 declare function buildCreateView(dialect: SqlDialect, viewName: string, plan: TViewPlan, columns: TViewColumnMapping[], resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
 //#endregion
@@ -230,11 +233,13 @@ interface TReplaceColumn {
   useDefault: boolean;
 }
 /**
- * The columns a full replace assigns on a SQL adapter: every non-ignored
- * descriptor (the same set `CREATE TABLE` emits) except the primary key —
- * the row is matched by the filter, and an omitted PK must never be nulled
- * or re-defaulted. Static value defaults are filled SDK-side before the
- * adapter sees the row, so only native function defaults are flagged.
+ * The columns a full replace assigns on a SQL adapter: the readable's
+ * `storedDescriptors` (non-ignored, not derived — a generated column is
+ * never assigned) except the primary key — the row is matched by the filter,
+ * and an omitted PK must never be nulled or re-defaulted. Static value
+ * defaults are filled SDK-side before the adapter sees the row, so only
+ * native function defaults are flagged. Ignored and derived descriptors in
+ * `fields` are skipped, so `fieldDescriptors` works too.
  */
 declare function replaceColumnsFor(fields: readonly TDbFieldMeta[], nativeFns: ReadonlySet<TDbDefaultFn>): TReplaceColumn[];
 /**
@@ -268,6 +273,17 @@ declare function buildUpdate(dialect: SqlDialect, table: string, data: Record<st
  * Builds a DELETE ... WHERE statement with optional LIMIT.
  */
 declare function buildDelete(dialect: SqlDialect, table: string, where: TSqlFragment, limit?: number): TSqlFragment;
+/**
+ * The expression a `@db.column.derived` column is generated from: the
+ * dialect's typed {@link SqlDialect.jsonExtract} over the (unqualified,
+ * quoted) JSON source column — the same extraction a view's JSON leaf uses,
+ * so both read a leaf identically. Parameter-free by contract; rendered in
+ * `CREATE TABLE` / `ADD COLUMN` as `GENERATED ALWAYS AS (<expr>)`.
+ *
+ * @throws when `field` is not derived or the dialect has no `jsonExtract`.
+ * @since 0.1.141
+ */
+declare function derivedColumnExpr(dialect: SqlDialect, field: TDbFieldMeta): string;
 /**
  * Builds a column projection (SELECT clause fields).
  */
@@ -368,4 +384,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoWindow, type TReplaceColumn, type TSqlFragment, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoWindow, type TReplaceColumn, type TSqlFragment, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue };

package/dist/index.d.mts

@@ -182,9 +182,12 @@ declare function renameGeoDistance(row: Record<string, unknown>): Record<string,
  * Builds a CREATE VIEW statement from a view plan and column mappings.
  *
  * Joins render in declaration order — `JOIN` (inner, the default) or
- * `LEFT JOIN` for `kind: "left"`. Column mappings carry PHYSICAL source
- * names; `resolveFieldRef` renders predicate refs (join ON, WHERE, HAVING
- * fallbacks) as `"table"."column"`.
+ * `LEFT JOIN` for `kind: "left"`; a `@db.alias` target renders as
+ * `JOIN "table" AS "Alias"` and is addressed by the alias everywhere else
+ * (since 0.1.141). Column mappings carry PHYSICAL source names (the alias
+ * name for an aliased join); `resolveFieldRef` renders predicate refs (join
+ * ON, WHERE, HAVING fallbacks) as `"table"."column"`. The entry table and a
+ * join target may be views.
  */
 declare function buildCreateView(dialect: SqlDialect, viewName: string, plan: TViewPlan, columns: TViewColumnMapping[], resolveFieldRef: (ref: AtscriptQueryFieldRef) => string): string;
 //#endregion
@@ -230,11 +233,13 @@ interface TReplaceColumn {
   useDefault: boolean;
 }
 /**
- * The columns a full replace assigns on a SQL adapter: every non-ignored
- * descriptor (the same set `CREATE TABLE` emits) except the primary key —
- * the row is matched by the filter, and an omitted PK must never be nulled
- * or re-defaulted. Static value defaults are filled SDK-side before the
- * adapter sees the row, so only native function defaults are flagged.
+ * The columns a full replace assigns on a SQL adapter: the readable's
+ * `storedDescriptors` (non-ignored, not derived — a generated column is
+ * never assigned) except the primary key — the row is matched by the filter,
+ * and an omitted PK must never be nulled or re-defaulted. Static value
+ * defaults are filled SDK-side before the adapter sees the row, so only
+ * native function defaults are flagged. Ignored and derived descriptors in
+ * `fields` are skipped, so `fieldDescriptors` works too.
  */
 declare function replaceColumnsFor(fields: readonly TDbFieldMeta[], nativeFns: ReadonlySet<TDbDefaultFn>): TReplaceColumn[];
 /**
@@ -268,6 +273,17 @@ declare function buildUpdate(dialect: SqlDialect, table: string, data: Record<st
  * Builds a DELETE ... WHERE statement with optional LIMIT.
  */
 declare function buildDelete(dialect: SqlDialect, table: string, where: TSqlFragment, limit?: number): TSqlFragment;
+/**
+ * The expression a `@db.column.derived` column is generated from: the
+ * dialect's typed {@link SqlDialect.jsonExtract} over the (unqualified,
+ * quoted) JSON source column — the same extraction a view's JSON leaf uses,
+ * so both read a leaf identically. Parameter-free by contract; rendered in
+ * `CREATE TABLE` / `ADD COLUMN` as `GENERATED ALWAYS AS (<expr>)`.
+ *
+ * @throws when `field` is not derived or the dialect has no `jsonExtract`.
+ * @since 0.1.141
+ */
+declare function derivedColumnExpr(dialect: SqlDialect, field: TDbFieldMeta): string;
 /**
  * Builds a column projection (SELECT clause fields).
  */
@@ -368,4 +384,4 @@ declare function parseRegexString(value: unknown): {
   flags: string;
 };
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoWindow, type TReplaceColumn, type TSqlFragment, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, type SqlDialect, type TFilterVisitorOptions, type TGeoCircle, type TGeoWindow, type TReplaceColumn, type TSqlFragment, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue };

package/dist/index.mjs

@@ -641,9 +641,12 @@ function viewAggExpr(dialect, c, resolveFieldRef) {
 * Builds a CREATE VIEW statement from a view plan and column mappings.
 *
 * Joins render in declaration order — `JOIN` (inner, the default) or
-* `LEFT JOIN` for `kind: "left"`. Column mappings carry PHYSICAL source
-* names; `resolveFieldRef` renders predicate refs (join ON, WHERE, HAVING
-* fallbacks) as `"table"."column"`.
+* `LEFT JOIN` for `kind: "left"`; a `@db.alias` target renders as
+* `JOIN "table" AS "Alias"` and is addressed by the alias everywhere else
+* (since 0.1.141). Column mappings carry PHYSICAL source names (the alias
+* name for an aliased join); `resolveFieldRef` renders predicate refs (join
+* ON, WHERE, HAVING fallbacks) as `"table"."column"`. The entry table and a
+* join target may be views.
 */
 function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
 	const selectCols = columns.map((c) => {
@@ -653,7 +656,8 @@ function buildCreateView(dialect, viewName, plan, columns, resolveFieldRef) {
 	for (const join of plan.joins) {
 		const onClause = queryNodeToSql(join.condition, resolveFieldRef);
 		const keyword = join.kind === "left" ? "LEFT JOIN" : "JOIN";
-		sql += ` ${keyword} ${dialect.quoteIdentifier(join.targetTable)} ON ${onClause}`;
+		const target = join.scope === join.targetTable ? dialect.quoteIdentifier(join.targetTable) : `${dialect.quoteIdentifier(join.targetTable)} AS ${dialect.quoteIdentifier(join.scope)}`;
+		sql += ` ${keyword} ${target} ON ${onClause}`;
 	}
 	if (plan.filter) {
 		const whereClause = queryNodeToSql(plan.filter, resolveFieldRef);
@@ -761,16 +765,18 @@ function buildSelect(dialect, table, where, controls) {
 */
 const SQL_DEFAULT = Symbol("SQL_DEFAULT");
 /**
-* The columns a full replace assigns on a SQL adapter: every non-ignored
-* descriptor (the same set `CREATE TABLE` emits) except the primary key —
-* the row is matched by the filter, and an omitted PK must never be nulled
-* or re-defaulted. Static value defaults are filled SDK-side before the
-* adapter sees the row, so only native function defaults are flagged.
+* The columns a full replace assigns on a SQL adapter: the readable's
+* `storedDescriptors` (non-ignored, not derived — a generated column is
+* never assigned) except the primary key — the row is matched by the filter,
+* and an omitted PK must never be nulled or re-defaulted. Static value
+* defaults are filled SDK-side before the adapter sees the row, so only
+* native function defaults are flagged. Ignored and derived descriptors in
+* `fields` are skipped, so `fieldDescriptors` works too.
 */
 function replaceColumnsFor(fields, nativeFns) {
 	const out = [];
 	for (const fd of fields) {
-		if (fd.ignored || fd.isPrimaryKey) continue;
+		if (fd.ignored || fd.isPrimaryKey || fd.derived) continue;
 		const def = fd.defaultValue;
 		out.push({
 			name: fd.physicalName,
@@ -867,6 +873,22 @@ function buildDelete(dialect, table, where, limit) {
 	});
 }
 /**
+* The expression a `@db.column.derived` column is generated from: the
+* dialect's typed {@link SqlDialect.jsonExtract} over the (unqualified,
+* quoted) JSON source column — the same extraction a view's JSON leaf uses,
+* so both read a leaf identically. Parameter-free by contract; rendered in
+* `CREATE TABLE` / `ADD COLUMN` as `GENERATED ALWAYS AS (<expr>)`.
+*
+* @throws when `field` is not derived or the dialect has no `jsonExtract`.
+* @since 0.1.141
+*/
+function derivedColumnExpr(dialect, field) {
+	const derived = field.derived;
+	if (!derived) throw new Error(`Column "${field.physicalName}" is not a derived column`);
+	if (!dialect.jsonExtract) throw new Error(`Derived column "${field.physicalName}": JSON extraction is not supported by this adapter`);
+	return dialect.jsonExtract(dialect.quoteIdentifier(derived.sourceColumn), derived.jsonPath, derived.type);
+}
+/**
 * Builds a column projection (SELECT clause fields).
 */
 function buildProjection(dialect, select) {
@@ -905,4 +927,4 @@ function parseRegexString(value) {
 	};
 }
 //#endregion
-export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue };
+export { AGG_FN_SQL, EMPTY_AND, EMPTY_OR, GEO_DISTANCE_ALIAS, SQL_DEFAULT, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildProjection, buildSelect, buildUpdate, buildWhere, createFilterVisitor, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, finalizeParams, geoWindowFromControls, groupKeySql, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, queryNodeToSql, queryOpToSql, quotedJsonPathSegments, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlStringLiteral, sqlTimeZoneLiteral, toSqlValue };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-sql-tools",
-  "version": "0.1.139",
+  "version": "0.1.141",
   "description": "Shared SQL builder utilities for @atscript database adapters.",
   "keywords": [
     "atscript",
@@ -38,11 +38,11 @@
   },
   "devDependencies": {
     "@uniqu/core": "^0.1.11",
-    "unplugin-atscript": "^0.1.92"
+    "unplugin-atscript": "^0.1.95"
   },
   "peerDependencies": {
     "@uniqu/core": "^0.1.11",
-    "@atscript/db": "^0.1.139"
+    "@atscript/db": "^0.1.141"
   },
   "scripts": {
     "build": "vp pack",