@storecraft/database-sql-base 1.0.0

package/src/con.helpers.json.mysql.js

@@ -0,0 +1,239 @@
+import { SelectQueryNode, sql } from "kysely"
+import { extract_first_selection, getJsonObjectArgs } from "./con.helpers.json.js"
+
+/**
+ * A MySQL helper for aggregating a subquery into a JSON array.
+ *
+ * NOTE: This helper is only guaranteed to fully work with the built-in `MysqlDialect`.
+ * While the produced SQL is compatible with all MySQL databases, some 3rd party dialects
+ * may not parse the nested JSON into arrays. In these cases you can use the built in
+ * `ParseJSONResultsPlugin` to parse the results.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * const result = await db
+ *   .selectFrom('person')
+ *   .select((eb) => [
+ *     'id',
+ *     jsonArrayFrom(
+ *       eb.selectFrom('pet')
+ *         .select(['pet.id as pet_id', 'pet.name'])
+ *         .whereRef('pet.owner_id', '=', 'person.id')
+ *         .orderBy('pet.name')
+ *     ).as('pets')
+ *   ])
+ *   .execute()
+ *
+ * result[0].id
+ * result[0].pets[0].pet_id
+ * result[0].pets[0].name
+ * ```
+ *
+ * The generated SQL (MySQL):
+ *
+ * ```sql
+ * select `id`, (
+ *   select cast(coalesce(json_arrayagg(json_object(
+ *     'pet_id', `agg`.`pet_id`,
+ *     'name', `agg`.`name`
+ *   )), '[]') as json) from (
+ *     select `pet`.`id` as `pet_id`, `pet`.`name`
+ *     from `pet`
+ *     where `pet`.`owner_id` = `person`.`id`
+ *     order by `pet`.`name`
+ *   ) as `agg`
+ * ) as `pets`
+ * from `person`
+ * ```
+ * 
+ * @template O
+ * @param {import("./con.helpers.json.js").SelectQueryBuilderExpression<O>} expr 
+ * @returns {import("kysely").RawBuilder<import("kysely").Simplify<O>[]>}
+ */
+export function mysql_jsonArrayFrom(expr) {
+  return sql`(select cast(coalesce(json_arrayagg(json_object(${sql.join(
+    getMysqlJsonObjectArgs(expr.toOperationNode(), 'agg'),
+  )})), '[]') as json) from ${expr} as agg)`
+}
+
+/**
+ * A SQLite helper for aggregating a subquery into a JSON array.
+ *
+ * NOTE: This helper only works correctly if you've installed the `ParseJSONResultsPlugin`.
+ * Otherwise the nested selections will be returned as JSON strings.
+ *
+ * The plugin can be installed like this:
+ *
+ * ```ts
+ * const db = new Kysely({
+ *   dialect: new SqliteDialect(config),
+ *   plugins: [new ParseJSONResultsPlugin()]
+ * })
+ * ```
+ *
+ * ### Examples
+ *
+ * ```ts
+ * const result = await db
+ *   .selectFrom('person')
+ *   .select((eb) => [
+ *     'id',
+ *     stringArrayFrom(
+ *       eb.selectFrom('pet')
+ *         .select('pet.name')
+ *         .whereRef('pet.owner_id', '=', 'person.id')
+ *         .orderBy('pet.name')
+ *     ).as('pets')
+ *   ])
+ *   .execute()
+ *
+ * result[0].pets = ['name1', 'name2', ....]
+ * ```
+ *
+ * The generated SQL (SQLite):
+ *
+ * ```sql
+ * select "id", (
+ *   select coalesce(json_group_array("agg"."name"), '[]') from (
+ *     select "pet"."name"
+ *     from "pet"
+ *     where "pet"."owner_id" = "person"."id"
+ *     order by "pet"."name"
+ *   ) as "agg"
+ * ) as "pets"
+ * from "person"
+ * ```
+ * @template O
+ * @param {import('./con.helpers.json.js').SelectQueryBuilderExpression<O>} expr 
+ * @returns {import('kysely').RawBuilder<import('kysely').Simplify<O>[]>}
+ */
+export function mysql_stringArrayFrom(expr) {
+  const arg = extract_first_selection(expr, 'agg');
+  return sql`(select cast(coalesce(json_arrayagg(${sql.join([arg])}), '[]') as json) from ${expr} as agg)`
+}
+
+
+/**
+ * A MySQL helper for turning a subquery into a JSON object.
+ *
+ * The subquery must only return one row.
+ *
+ * NOTE: This helper is only guaranteed to fully work with the built-in `MysqlDialect`.
+ * While the produced SQL is compatible with all MySQL databases, some 3rd party dialects
+ * may not parse the nested JSON into objects. In these cases you can use the built in
+ * `ParseJSONResultsPlugin` to parse the results.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * const result = await db
+ *   .selectFrom('person')
+ *   .select((eb) => [
+ *     'id',
+ *     jsonObjectFrom(
+ *       eb.selectFrom('pet')
+ *         .select(['pet.id as pet_id', 'pet.name'])
+ *         .whereRef('pet.owner_id', '=', 'person.id')
+ *         .where('pet.is_favorite', '=', true)
+ *     ).as('favorite_pet')
+ *   ])
+ *   .execute()
+ *
+ * result[0].id
+ * result[0].favorite_pet.pet_id
+ * result[0].favorite_pet.name
+ * ```
+ *
+ * The generated SQL (MySQL):
+ *
+ * ```sql
+ * select `id`, (
+ *   select json_object(
+ *     'pet_id', `obj`.`pet_id`,
+ *     'name', `obj`.`name`
+ *   ) from (
+ *     select `pet`.`id` as `pet_id`, `pet`.`name`
+ *     from `pet`
+ *     where `pet`.`owner_id` = `person`.`id`
+ *     and `pet`.`is_favorite` = ?
+ *   ) as obj
+ * ) as `favorite_pet`
+ * from `person`
+ * ```
+ * 
+ * @template O
+ * @param {import("./con.helpers.json.js").SelectQueryBuilderExpression<O>} expr 
+ * @returns {import("kysely").RawBuilder<import("kysely").Simplify<O> | null>}
+ */
+export function mysql_jsonObjectFrom(expr) {
+  return sql`(select json_object(${sql.join(
+    getMysqlJsonObjectArgs(expr.toOperationNode(), 'obj'),
+  )}) from ${expr} as obj)`
+}
+
+/**
+ * The MySQL `json_object` function.
+ *
+ * NOTE: This helper is only guaranteed to fully work with the built-in `MysqlDialect`.
+ * While the produced SQL is compatible with all MySQL databases, some 3rd party dialects
+ * may not parse the nested JSON into objects. In these cases you can use the built in
+ * `ParseJSONResultsPlugin` to parse the results.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * const result = await db
+ *   .selectFrom('person')
+ *   .select((eb) => [
+ *     'id',
+ *     jsonBuildObject({
+ *       first: eb.ref('first_name'),
+ *       last: eb.ref('last_name'),
+ *       full: eb.fn('concat', ['first_name', eb.val(' '), 'last_name'])
+ *     }).as('name')
+ *   ])
+ *   .execute()
+ *
+ * result[0].id
+ * result[0].name.first
+ * result[0].name.last
+ * result[0].name.full
+ * ```
+ *
+ * The generated SQL (MySQL):
+ *
+ * ```sql
+ * select "id", json_object(
+ *   'first', first_name,
+ *   'last', last_name,
+ *   'full', concat(`first_name`, ?, `last_name`)
+ * ) as "name"
+ * from "person"
+ * ```
+ * 
+ * @template {Record<string, import("kysely").Expression<unknown>>} O
+ * @param {O} obj 
+ * @returns {import("kysely").RawBuilder<import("kysely").Simplify<{[K in keyof O]: O[K] extends Expression<infer V> ? V : never}>>}
+ */
+export function mysql_jsonBuildObject(obj) {
+  return sql`json_object(${sql.join(
+    Object.keys(obj).flatMap((k) => [sql.lit(k), obj[k]]),
+  )})`
+}
+
+/**
+ * 
+ * @param {SelectQueryNode} node 
+ * @param {string} table 
+ * @returns {import("kysely").Expression<unknown>[]}
+ */
+function getMysqlJsonObjectArgs(node, table) {
+  try {
+    return getJsonObjectArgs(node, table)
+  } catch {
+    throw new Error(
+      'MySQL jsonArrayFrom and jsonObjectFrom functions can only handle explicit selections due to limitations of the json_object function. selectAll() is not allowed in the subquery.',
+    )
+  }
+}

package/src/con.helpers.json.postgres.js

@@ -0,0 +1,223 @@
+import { sql} from 'kysely'
+import { extract_first_selection } from './con.helpers.json.js';
+
+
+/**
+ * A SQLite helper for aggregating a subquery into a JSON array.
+ *
+ * NOTE: This helper only works correctly if you've installed the `ParseJSONResultsPlugin`.
+ * Otherwise the nested selections will be returned as JSON strings.
+ *
+ * The plugin can be installed like this:
+ *
+ * ```ts
+ * const db = new Kysely({
+ *   dialect: new SqliteDialect(config),
+ *   plugins: [new ParseJSONResultsPlugin()]
+ * })
+ * ```
+ *
+ * ### Examples
+ *
+ * ```ts
+ * const result = await db
+ *   .selectFrom('person')
+ *   .select((eb) => [
+ *     'id',
+ *     stringArrayFrom(
+ *       eb.selectFrom('pet')
+ *         .select('pet.name')
+ *         .whereRef('pet.owner_id', '=', 'person.id')
+ *         .orderBy('pet.name')
+ *     ).as('pets')
+ *   ])
+ *   .execute()
+ *
+ * result[0].pets = ['name1', 'name2', ....]
+ * ```
+ *
+ * The generated SQL (SQLite):
+ *
+ * ```sql
+ * select "id", (
+ *   select coalesce(json_group_array("agg"."name"), '[]') from (
+ *     select "pet"."name"
+ *     from "pet"
+ *     where "pet"."owner_id" = "person"."id"
+ *     order by "pet"."name"
+ *   ) as "agg"
+ * ) as "pets"
+ * from "person"
+ * ```
+ * @template O
+ * @param {import('./con.helpers.json.js').SelectQueryBuilderExpression<O>} expr 
+ * @returns {import('kysely').RawBuilder<import('kysely').Simplify<O>[]>}
+ */
+export function pg_stringArrayFrom(expr) {
+  const arg = extract_first_selection(expr, 'agg');
+  return sql`(select coalesce(json_agg(${sql.join([arg])}), '[]') from ${expr} as agg)`
+}
+
+/**
+ * A postgres helper for aggregating a subquery (or other expression) into a JSONB array.
+ *
+ * ### Examples
+ *
+ * <!-- siteExample("select", "Nested array", 110) -->
+ *
+ * While kysely is not an ORM and it doesn't have the concept of relations, we do provide
+ * helpers for fetching nested objects and arrays in a single query. In this example we
+ * use the `jsonArrayFrom` helper to fetch person's pets along with the person's id.
+ *
+ * Please keep in mind that the helpers under the `kysely/helpers` folder, including
+ * `jsonArrayFrom`, are not guaranteed to work with third party dialects. In order for
+ * them to work, the dialect must automatically parse the `json` data type into
+ * javascript JSON values like objects and arrays. Some dialects might simply return
+ * the data as a JSON string. In these cases you can use the built in `ParseJSONResultsPlugin`
+ * to parse the results.
+ *
+ * ```ts
+ * import { jsonArrayFrom } from 'kysely/helpers/postgres'
+ *
+ * const result = await db
+ *   .selectFrom('person')
+ *   .select((eb) => [
+ *     'id',
+ *     jsonArrayFrom(
+ *       eb.selectFrom('pet')
+ *         .select(['pet.id as pet_id', 'pet.name'])
+ *         .whereRef('pet.owner_id', '=', 'person.id')
+ *         .orderBy('pet.name')
+ *     ).as('pets')
+ *   ])
+ *   .execute()
+ * ```
+ *
+ * The generated SQL (PostgreSQL):
+ *
+ * ```sql
+ * select "id", (
+ *   select coalesce(json_agg(agg), '[]') from (
+ *     select "pet"."id" as "pet_id", "pet"."name"
+ *     from "pet"
+ *     where "pet"."owner_id" = "person"."id"
+ *     order by "pet"."name"
+ *   ) as agg
+ * ) as "pets"
+ * from "person"
+ * ```
+ * @template O
+ * @param {import('kysely').Expression<O>} expr 
+ * @returns {import('kysely').RawBuilder<import('kysely').Simplify<O>[]>}
+ */
+export function pg_jsonArrayFrom(expr) {
+  return sql`(select coalesce(json_agg(agg), '[]') from ${expr} as agg)`
+}
+
+/**
+ * A postgres helper for turning a subquery (or other expression) into a JSON object.
+ *
+ * The subquery must only return one row.
+ *
+ * ### Examples
+ *
+ * <!-- siteExample("select", "Nested object", 120) -->
+ *
+ * While kysely is not an ORM and it doesn't have the concept of relations, we do provide
+ * helpers for fetching nested objects and arrays in a single query. In this example we
+ * use the `jsonObjectFrom` helper to fetch person's favorite pet along with the person's id.
+ *
+ * Please keep in mind that the helpers under the `kysely/helpers` folder, including
+ * `jsonObjectFrom`, are not guaranteed to work with 3rd party dialects. In order for
+ * them to work, the dialect must automatically parse the `json` data type into
+ * javascript JSON values like objects and arrays. Some dialects might simply return
+ * the data as a JSON string. In these cases you can use the built in `ParseJSONResultsPlugin`
+ * to parse the results.
+ *
+ * ```ts
+ * import { jsonObjectFrom } from 'kysely/helpers/postgres'
+ *
+ * const result = await db
+ *   .selectFrom('person')
+ *   .select((eb) => [
+ *     'id',
+ *     jsonObjectFrom(
+ *       eb.selectFrom('pet')
+ *         .select(['pet.id as pet_id', 'pet.name'])
+ *         .whereRef('pet.owner_id', '=', 'person.id')
+ *         .where('pet.is_favorite', '=', true)
+ *     ).as('favorite_pet')
+ *   ])
+ *   .execute()
+ * ```
+ *
+ * The generated SQL (PostgreSQL):
+ *
+ * ```sql
+ * select "id", (
+ *   select to_json(obj) from (
+ *     select "pet"."id" as "pet_id", "pet"."name"
+ *     from "pet"
+ *     where "pet"."owner_id" = "person"."id"
+ *     and "pet"."is_favorite" = $1
+ *   ) as obj
+ * ) as "favorite_pet"
+ * from "person"
+ * ```
+ * @template O
+ * @param {import('kysely').Expression<O>} expr 
+ * @returns {import('kysely').RawBuilder<import('kysely').Simplify<O> | null>}
+ */
+export function pg_jsonObjectFrom(expr) {
+  return sql`(select to_json(obj) from ${expr} as obj)`
+}
+
+/**
+ * The PostgreSQL `json_build_object` function.
+ *
+ * NOTE: This helper is only guaranteed to fully work with the built-in `PostgresDialect`.
+ * While the produced SQL is compatible with all PostgreSQL databases, some 3rd party dialects
+ * may not parse the nested JSON into objects. In these cases you can use the built in
+ * `ParseJSONResultsPlugin` to parse the results.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * const result = await db
+ *   .selectFrom('person')
+ *   .select((eb) => [
+ *     'id',
+ *     jsonBuildObject({
+ *       first: eb.ref('first_name'),
+ *       last: eb.ref('last_name'),
+ *       full: sql<string>`first_name || ' ' || last_name`
+ *     }).as('name')
+ *   ])
+ *   .execute()
+ *
+ * result[0].id
+ * result[0].name.first
+ * result[0].name.last
+ * result[0].name.full
+ * ```
+ *
+ * The generated SQL (PostgreSQL):
+ *
+ * ```sql
+ * select "id", json_build_object(
+ *   'first', first_name,
+ *   'last', last_name,
+ *   'full', first_name || ' ' || last_name
+ * ) as "name"
+ * from "person"
+ * ```
+ * @template {Record<string, import('kysely').Expression<unknown>>} O
+ * @param {O} obj 
+ * @returns { import('kysely').RawBuilder<import('kysely').Simplify<{[K in keyof O]: O[K] extends Expression<infer V> ? V : never}>>}
+>}
+ */
+export function pg_jsonBuildObject(obj) {
+  return sql`json_build_object(${sql.join(
+    Object.keys(obj).flatMap((k) => [sql.lit(k), obj[k]]),
+  )})`
+}