Merge pull request #169 from bknd-io/release/0.13

Release 0.13

app/src/data/api/DataController.ts

@@ -1,6 +1,4 @@
-import { $console, isDebug, tbValidator as tb } from "core";
-import { StringEnum } from "core/utils";
-import * as tbbox from "@sinclair/typebox";
+import { $console, isDebug } from "core";
 import {
    DataPermissions,
    type EntityData,
@@ -8,14 +6,15 @@ import {
    type MutatorResponse,
    type RepoQuery,
    type RepositoryResponse,
-   querySchema,
+   repoQuery,
 } from "data";
 import type { Handler } from "hono/types";
 import type { ModuleBuildContext } from "modules";
 import { Controller } from "modules/Controller";
+import { jsc, s, describeRoute, schemaToSpec } from "core/object/schema";
 import * as SystemPermissions from "modules/permissions";
 import type { AppDataConfig } from "../data-schema";
-const { Type } = tbbox;
+import { omitKeys } from "core/utils";
 
 export class DataController extends Controller {
    constructor(
@@ -71,6 +70,7 @@ export class DataController extends Controller {
    override getController() {
       const { permission, auth } = this.middlewares;
       const hono = this.create().use(auth(), permission(SystemPermissions.accessApi));
+      const entitiesEnum = this.getEntitiesEnum(this.em);
 
       // @todo: sample implementation how to augment handler with additional info
       function handler<HH extends Handler>(name: string, h: HH): any {
@@ -83,6 +83,10 @@ export class DataController extends Controller {
       // info
       hono.get(
          "/",
+         describeRoute({
+            summary: "Retrieve data configuration",
+            tags: ["data"],
+         }),
          handler("data info", (c) => {
             // sample implementation
             return c.json(this.em.toJSON());
@@ -90,49 +94,75 @@ export class DataController extends Controller {
       );
 
       // sync endpoint
-      hono.get("/sync", permission(DataPermissions.databaseSync), async (c) => {
-         const force = c.req.query("force") === "1";
-         const drop = c.req.query("drop") === "1";
-         //console.log("force", force);
-         const tables = await this.em.schema().introspect();
-         //console.log("tables", tables);
-         const changes = await this.em.schema().sync({
-            force,
-            drop,
-         });
-         return c.json({ tables: tables.map((t) => t.name), changes });
-      });
+      hono.get(
+         "/sync",
+         permission(DataPermissions.databaseSync),
+         describeRoute({
+            summary: "Sync database schema",
+            tags: ["data"],
+         }),
+         jsc(
+            "query",
+            s.partialObject({
+               force: s.boolean(),
+               drop: s.boolean(),
+            }),
+         ),
+         async (c) => {
+            const { force, drop } = c.req.valid("query");
+            //console.log("force", force);
+            const tables = await this.em.schema().introspect();
+            //console.log("tables", tables);
+            const changes = await this.em.schema().sync({
+               force,
+               drop,
+            });
+            return c.json({ tables: tables.map((t) => t.name), changes });
+         },
+      );
 
       /**
        * Schema endpoints
        */
       // read entity schema
-      hono.get("/schema.json", permission(DataPermissions.entityRead), async (c) => {
-         const $id = `${this.config.basepath}/schema.json`;
-         const schemas = Object.fromEntries(
-            this.em.entities.map((e) => [
-               e.name,
-               {
-                  $ref: `${this.config.basepath}/schemas/${e.name}`,
-               },
-            ]),
-         );
-         return c.json({
-            $schema: "https://json-schema.org/draft/2020-12/schema",
-            $id,
-            properties: schemas,
-         });
-      });
+      hono.get(
+         "/schema.json",
+         permission(DataPermissions.entityRead),
+         describeRoute({
+            summary: "Retrieve data schema",
+            tags: ["data"],
+         }),
+         async (c) => {
+            const $id = `${this.config.basepath}/schema.json`;
+            const schemas = Object.fromEntries(
+               this.em.entities.map((e) => [
+                  e.name,
+                  {
+                     $ref: `${this.config.basepath}/schemas/${e.name}`,
+                  },
+               ]),
+            );
+            return c.json({
+               $schema: "https://json-schema.org/draft/2020-12/schema",
+               $id,
+               properties: schemas,
+            });
+         },
+      );
 
       // read schema
       hono.get(
          "/schemas/:entity/:context?",
          permission(DataPermissions.entityRead),
-         tb(
+         describeRoute({
+            summary: "Retrieve entity schema",
+            tags: ["data"],
+         }),
+         jsc(
             "param",
-            Type.Object({
-               entity: Type.String(),
-               context: Type.Optional(StringEnum(["create", "update"])),
+            s.object({
+               entity: entitiesEnum,
+               context: s.string({ enum: ["create", "update"], default: "create" }).optional(),
             }),
          ),
          async (c) => {
@@ -161,30 +191,39 @@ export class DataController extends Controller {
       /**
        * Info endpoints
        */
-      hono.get("/info/:entity", async (c) => {
-         const { entity } = c.req.param();
-         if (!this.entityExists(entity)) {
-            return this.notFound(c);
-         }
-         const _entity = this.em.entity(entity);
-         const fields = _entity.fields.map((f) => f.name);
-         const $rels = (r: any) =>
-            r.map((r: any) => ({
-               entity: r.other(_entity).entity.name,
-               ref: r.other(_entity).reference,
-            }));
+      hono.get(
+         "/info/:entity",
+         permission(DataPermissions.entityRead),
+         describeRoute({
+            summary: "Retrieve entity info",
+            tags: ["data"],
+         }),
+         jsc("param", s.object({ entity: entitiesEnum })),
+         async (c) => {
+            const { entity } = c.req.param();
+            if (!this.entityExists(entity)) {
+               return this.notFound(c);
+            }
+            const _entity = this.em.entity(entity);
+            const fields = _entity.fields.map((f) => f.name);
+            const $rels = (r: any) =>
+               r.map((r: any) => ({
+                  entity: r.other(_entity).entity.name,
+                  ref: r.other(_entity).reference,
+               }));
 
-         return c.json({
-            name: _entity.name,
-            fields,
-            relations: {
-               all: $rels(this.em.relations.relationsOf(_entity)),
-               listable: $rels(this.em.relations.listableRelationsOf(_entity)),
-               source: $rels(this.em.relations.sourceRelationsOf(_entity)),
-               target: $rels(this.em.relations.targetRelationsOf(_entity)),
-            },
-         });
-      });
+            return c.json({
+               name: _entity.name,
+               fields,
+               relations: {
+                  all: $rels(this.em.relations.relationsOf(_entity)),
+                  listable: $rels(this.em.relations.listableRelationsOf(_entity)),
+                  source: $rels(this.em.relations.sourceRelationsOf(_entity)),
+                  target: $rels(this.em.relations.targetRelationsOf(_entity)),
+               },
+            });
+         },
+      );
 
       return hono.all("*", (c) => c.notFound());
    }
@@ -193,10 +232,7 @@ export class DataController extends Controller {
       const { permission } = this.middlewares;
       const hono = this.create();
 
-      const definedEntities = this.em.entities.map((e) => e.name);
-      const tbNumber = Type.Transform(Type.String({ pattern: "^[1-9][0-9]{0,}$" }))
-         .Decode(Number.parseInt)
-         .Encode(String);
+      const entitiesEnum = this.getEntitiesEnum(this.em);
 
       /**
        * Function endpoints
@@ -205,14 +241,19 @@ export class DataController extends Controller {
       hono.post(
          "/:entity/fn/count",
          permission(DataPermissions.entityRead),
-         tb("param", Type.Object({ entity: Type.String() })),
+         describeRoute({
+            summary: "Count entities",
+            tags: ["data"],
+         }),
+         jsc("param", s.object({ entity: entitiesEnum })),
+         jsc("json", repoQuery.properties.where),
          async (c) => {
             const { entity } = c.req.valid("param");
             if (!this.entityExists(entity)) {
                return this.notFound(c);
             }
 
-            const where = (await c.req.json()) as any;
+            const where = c.req.valid("json") as any;
             const result = await this.em.repository(entity).count(where);
             return c.json({ entity, count: result.count });
          },
@@ -222,14 +263,19 @@ export class DataController extends Controller {
       hono.post(
          "/:entity/fn/exists",
          permission(DataPermissions.entityRead),
-         tb("param", Type.Object({ entity: Type.String() })),
+         describeRoute({
+            summary: "Check if entity exists",
+            tags: ["data"],
+         }),
+         jsc("param", s.object({ entity: entitiesEnum })),
+         jsc("json", repoQuery.properties.where),
          async (c) => {
             const { entity } = c.req.valid("param");
             if (!this.entityExists(entity)) {
                return this.notFound(c);
             }
 
-            const where = c.req.json() as any;
+            const where = c.req.valid("json") as any;
             const result = await this.em.repository(entity).exists(where);
             return c.json({ entity, exists: result.exists });
          },
@@ -239,13 +285,31 @@ export class DataController extends Controller {
        * Read endpoints
        */
       // read many
+      const saveRepoQuery = s.partialObject({
+         ...omitKeys(repoQuery.properties, ["with"]),
+         sort: s.string({ default: "id" }),
+         select: s.array(s.string()),
+         join: s.array(s.string()),
+      });
+      const saveRepoQueryParams = (pick: string[] = Object.keys(repoQuery.properties)) => [
+         ...(schemaToSpec(saveRepoQuery, "query").parameters?.filter(
+            // @ts-ignore
+            (p) => pick.includes(p.name),
+         ) as any),
+      ];
+
       hono.get(
          "/:entity",
+         describeRoute({
+            summary: "Read many",
+            parameters: saveRepoQueryParams(["limit", "offset", "sort", "select", "join"]),
+            tags: ["data"],
+         }),
          permission(DataPermissions.entityRead),
-         tb("param", Type.Object({ entity: Type.String() })),
-         tb("query", querySchema),
+         jsc("param", s.object({ entity: entitiesEnum })),
+         jsc("query", repoQuery, { skipOpenAPI: true }),
          async (c) => {
-            const { entity } = c.req.param();
+            const { entity } = c.req.valid("param");
             if (!this.entityExists(entity)) {
                return this.notFound(c);
             }
@@ -259,17 +323,22 @@ export class DataController extends Controller {
       // read one
       hono.get(
          "/:entity/:id",
+         describeRoute({
+            summary: "Read one",
+            parameters: saveRepoQueryParams(["offset", "sort", "select"]),
+            tags: ["data"],
+         }),
          permission(DataPermissions.entityRead),
-         tb(
+         jsc(
             "param",
-            Type.Object({
-               entity: Type.String(),
-               id: tbNumber,
+            s.object({
+               entity: entitiesEnum,
+               id: s.string(),
             }),
          ),
-         tb("query", querySchema),
+         jsc("query", repoQuery, { skipOpenAPI: true }),
          async (c) => {
-            const { entity, id } = c.req.param();
+            const { entity, id } = c.req.valid("param");
             if (!this.entityExists(entity)) {
                return this.notFound(c);
             }
@@ -283,18 +352,23 @@ export class DataController extends Controller {
       // read many by reference
       hono.get(
          "/:entity/:id/:reference",
+         describeRoute({
+            summary: "Read many by reference",
+            parameters: saveRepoQueryParams(),
+            tags: ["data"],
+         }),
          permission(DataPermissions.entityRead),
-         tb(
+         jsc(
             "param",
-            Type.Object({
-               entity: Type.String(),
-               id: tbNumber,
-               reference: Type.String(),
+            s.object({
+               entity: entitiesEnum,
+               id: s.string(),
+               reference: s.string(),
             }),
          ),
-         tb("query", querySchema),
+         jsc("query", repoQuery, { skipOpenAPI: true }),
          async (c) => {
-            const { entity, id, reference } = c.req.param();
+            const { entity, id, reference } = c.req.valid("param");
             if (!this.entityExists(entity)) {
                return this.notFound(c);
             }
@@ -309,17 +383,33 @@ export class DataController extends Controller {
       );
 
       // func query
+      const fnQuery = s.partialObject({
+         ...saveRepoQuery.properties,
+         with: s.object({}),
+      });
       hono.post(
          "/:entity/query",
+         describeRoute({
+            summary: "Query entities",
+            requestBody: {
+               content: {
+                  "application/json": {
+                     schema: fnQuery.toJSON(),
+                     example: fnQuery.template({ withOptional: true }),
+                  },
+               },
+            },
+            tags: ["data"],
+         }),
          permission(DataPermissions.entityRead),
-         tb("param", Type.Object({ entity: Type.String() })),
-         tb("json", querySchema),
+         jsc("param", s.object({ entity: entitiesEnum })),
+         jsc("json", repoQuery, { skipOpenAPI: true }),
          async (c) => {
-            const { entity } = c.req.param();
+            const { entity } = c.req.valid("param");
             if (!this.entityExists(entity)) {
                return this.notFound(c);
             }
-            const options = (await c.req.valid("json")) as RepoQuery;
+            const options = (await c.req.json()) as RepoQuery;
             const result = await this.em.repository(entity).findMany(options);
 
             return c.json(this.repoResult(result), { status: result.data ? 200 : 404 });
@@ -332,11 +422,15 @@ export class DataController extends Controller {
       // insert one
       hono.post(
          "/:entity",
+         describeRoute({
+            summary: "Insert one or many",
+            tags: ["data"],
+         }),
          permission(DataPermissions.entityCreate),
-         tb("param", Type.Object({ entity: Type.String() })),
-         tb("json", Type.Union([Type.Object({}), Type.Array(Type.Object({}))])),
+         jsc("param", s.object({ entity: entitiesEnum })),
+         jsc("json", s.anyOf([s.object({}), s.array(s.object({}))])),
          async (c) => {
-            const { entity } = c.req.param();
+            const { entity } = c.req.valid("param");
             if (!this.entityExists(entity)) {
                return this.notFound(c);
             }
@@ -355,13 +449,17 @@ export class DataController extends Controller {
       // update many
       hono.patch(
          "/:entity",
+         describeRoute({
+            summary: "Update many",
+            tags: ["data"],
+         }),
          permission(DataPermissions.entityUpdate),
-         tb("param", Type.Object({ entity: Type.String() })),
-         tb(
+         jsc("param", s.object({ entity: entitiesEnum })),
+         jsc(
             "json",
-            Type.Object({
-               update: Type.Object({}),
-               where: querySchema.properties.where,
+            s.object({
+               update: s.object({}),
+               where: repoQuery.properties.where,
             }),
          ),
          async (c) => {
@@ -382,10 +480,15 @@ export class DataController extends Controller {
       // update one
       hono.patch(
          "/:entity/:id",
+         describeRoute({
+            summary: "Update one",
+            tags: ["data"],
+         }),
          permission(DataPermissions.entityUpdate),
-         tb("param", Type.Object({ entity: Type.String(), id: tbNumber })),
+         jsc("param", s.object({ entity: entitiesEnum, id: s.number() })),
+         jsc("json", s.object({})),
          async (c) => {
-            const { entity, id } = c.req.param();
+            const { entity, id } = c.req.valid("param");
             if (!this.entityExists(entity)) {
                return this.notFound(c);
             }
@@ -399,10 +502,14 @@ export class DataController extends Controller {
       // delete one
       hono.delete(
          "/:entity/:id",
+         describeRoute({
+            summary: "Delete one",
+            tags: ["data"],
+         }),
          permission(DataPermissions.entityDelete),
-         tb("param", Type.Object({ entity: Type.String(), id: tbNumber })),
+         jsc("param", s.object({ entity: entitiesEnum, id: s.number() })),
          async (c) => {
-            const { entity, id } = c.req.param();
+            const { entity, id } = c.req.valid("param");
             if (!this.entityExists(entity)) {
                return this.notFound(c);
             }
@@ -415,15 +522,19 @@ export class DataController extends Controller {
       // delete many
       hono.delete(
          "/:entity",
+         describeRoute({
+            summary: "Delete many",
+            tags: ["data"],
+         }),
          permission(DataPermissions.entityDelete),
-         tb("param", Type.Object({ entity: Type.String() })),
-         tb("json", querySchema.properties.where),
+         jsc("param", s.object({ entity: entitiesEnum })),
+         jsc("json", repoQuery.properties.where),
          async (c) => {
-            const { entity } = c.req.param();
+            const { entity } = c.req.valid("param");
             if (!this.entityExists(entity)) {
                return this.notFound(c);
             }
-            const where = c.req.valid("json") as RepoQuery["where"];
+            const where = (await c.req.json()) as RepoQuery["where"];
             const result = await this.em.mutator(entity).deleteWhere(where);
 
             return c.json(this.mutatorResult(result));

app/src/data/entities/Mutator.ts

@@ -6,7 +6,7 @@ import type { Entity, EntityData, EntityManager } from "../entities";
 import { InvalidSearchParamsException } from "../errors";
 import { MutatorEvents } from "../events";
 import { RelationMutator } from "../relations";
-import type { RepoQuery } from "../server/data-query-impl";
+import type { RepoQuery } from "../server/query";
 
 type MutatorQB =
    | InsertQueryBuilder<any, any, any>

app/src/data/entities/query/JoinBuilder.ts

@@ -20,6 +20,7 @@ export class JoinBuilder {
 
    // @todo: returns multiple on manytomany (edit: so?)
    static getJoinedEntityNames(em: EntityManager<any>, entity: Entity, joins: string[]): string[] {
+      console.log("join", joins);
       return joins.flatMap((join) => {
          const relation = em.relationOf(entity.name, join);
          if (!relation) {

app/src/data/entities/query/Repository.ts

@@ -2,10 +2,9 @@ import type { DB as DefaultDB, PrimaryFieldType } from "core";
 import { $console } from "core";
 import { type EmitsEvents, EventManager } from "core/events";
 import { type SelectQueryBuilder, sql } from "kysely";
-import { cloneDeep } from "lodash-es";
 import { InvalidSearchParamsException } from "../../errors";
 import { MutatorEvents, RepositoryEvents } from "../../events";
-import { type RepoQuery, defaultQuerySchema } from "../../server/data-query-impl";
+import { type RepoQuery, getRepoQueryTemplate } from "data/server/query";
 import {
    type Entity,
    type EntityData,
@@ -84,14 +83,14 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
       }
    }
 
-   getValidOptions(options?: Partial<RepoQuery>): RepoQuery {
+   getValidOptions(options?: RepoQuery): RepoQuery {
       const entity = this.entity;
       // @todo: if not cloned deep, it will keep references and error if multiple requests come in
       const validated = {
-         ...cloneDeep(defaultQuerySchema),
+         ...structuredClone(getRepoQueryTemplate()),
          sort: entity.getDefaultSort(),
          select: entity.getSelect(),
-      };
+      } satisfies Required<RepoQuery>;
 
       if (!options) return validated;
 
@@ -99,12 +98,15 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
          if (!validated.select.includes(options.sort.by)) {
             throw new InvalidSearchParamsException(`Invalid sort field "${options.sort.by}"`);
          }
-         if (!["asc", "desc"].includes(options.sort.dir)) {
+         if (!["asc", "desc"].includes(options.sort.dir!)) {
             throw new InvalidSearchParamsException(`Invalid sort direction "${options.sort.dir}"`);
          }
 
          this.checkIndex(entity.name, options.sort.by, "sort");
-         validated.sort = options.sort;
+         validated.sort = {
+            dir: "asc",
+            ...options.sort,
+         };
       }
 
       if (options.select && options.select.length > 0) {
@@ -505,7 +507,7 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
       };
    }
 
-   async exists(where: Required<RepoQuery["where"]>): Promise<RepositoryExistsResponse> {
+   async exists(where: Required<RepoQuery>["where"]): Promise<RepositoryExistsResponse> {
       const entity = this.entity;
       const options = this.getValidOptions({ where });
 
@@ -513,7 +515,7 @@ export class Repository<TBD extends object = DefaultDB, TB extends keyof TBD = a
       let qb = this.conn.selectFrom(entity.name).select(selector);
 
       // add mandatory where
-      qb = WhereBuilder.addClause(qb, options.where).limit(1);
+      qb = WhereBuilder.addClause(qb, options.where!).limit(1);
 
       const { result, ...compiled } = await this.executeQb(qb);
 

app/src/data/entities/query/WhereBuilder.ts

@@ -90,6 +90,7 @@ const expressions = [
 export type WhereQuery = FilterQuery<typeof expressions>;
 
 const validator = makeValidator(expressions);
+export const expressionKeys = validator.expressionKeys;
 
 export class WhereBuilder {
    static addClause<QB extends WhereQb>(qb: QB, query: WhereQuery) {

app/src/data/events/index.ts

@@ -1,7 +1,7 @@
 import { $console, type PrimaryFieldType } from "core";
 import { Event, InvalidEventReturn } from "core/events";
 import type { Entity, EntityData } from "../entities";
-import type { RepoQuery } from "../server/data-query-impl";
+import type { RepoQuery } from "data/server/query";
 
 export class MutatorInsertBefore extends Event<{ entity: Entity; data: EntityData }, EntityData> {
    static override slug = "mutator-insert-before";

app/src/data/index.ts

@@ -10,10 +10,11 @@ export * from "./connection";
 export {
    type RepoQuery,
    type RepoQueryIn,
-   defaultQuerySchema,
-   querySchema,
-   whereSchema,
-} from "./server/data-query-impl";
+   getRepoQueryTemplate,
+   repoQuery,
+} from "./server/query";
+
+export type { WhereQuery } from "./entities/query/WhereBuilder";
 
 export { KyselyPluginRunner } from "./plugins/KyselyPluginRunner";
 

app/src/data/relations/EntityRelation.ts

@@ -6,7 +6,7 @@ import {
    type MutationInstructionResponse,
    RelationHelper,
 } from "../relations";
-import type { RepoQuery } from "../server/data-query-impl";
+import type { RepoQuery } from "../server/query";
 import type { RelationType } from "./relation-types";
 import * as tbbox from "@sinclair/typebox";
 const { Type } = tbbox;

app/src/data/relations/ManyToManyRelation.ts

@@ -2,7 +2,7 @@ import type { Static } from "core/utils";
 import type { ExpressionBuilder } from "kysely";
 import { Entity, type EntityManager } from "../entities";
 import { type Field, PrimaryField } from "../fields";
-import type { RepoQuery } from "../server/data-query-impl";
+import type { RepoQuery } from "../server/query";
 import { EntityRelation, type KyselyQueryBuilder } from "./EntityRelation";
 import { EntityRelationAnchor } from "./EntityRelationAnchor";
 import { RelationField } from "./RelationField";

app/src/data/relations/ManyToOneRelation.ts

@@ -3,7 +3,7 @@ import { snakeToPascalWithSpaces } from "core/utils";
 import type { Static } from "core/utils";
 import type { ExpressionBuilder } from "kysely";
 import type { Entity, EntityManager } from "../entities";
-import type { RepoQuery } from "../server/data-query-impl";
+import type { RepoQuery } from "../server/query";
 import { EntityRelation, type KyselyQueryBuilder } from "./EntityRelation";
 import { EntityRelationAnchor } from "./EntityRelationAnchor";
 import { RelationField, type RelationFieldBaseConfig } from "./RelationField";

app/src/data/relations/PolymorphicRelation.ts

@@ -2,7 +2,7 @@ import type { Static } from "core/utils";
 import type { ExpressionBuilder } from "kysely";
 import type { Entity, EntityManager } from "../entities";
 import { NumberField, TextField } from "../fields";
-import type { RepoQuery } from "../server/data-query-impl";
+import type { RepoQuery } from "../server/query";
 import { EntityRelation, type KyselyJsonFrom, type KyselyQueryBuilder } from "./EntityRelation";
 import { EntityRelationAnchor } from "./EntityRelationAnchor";
 import { type RelationType, RelationTypes } from "./relation-types";

app/src/data/server/data-query-impl.ts

@@ -1,148 +0,0 @@
-import type { TThis } from "@sinclair/typebox";
-import { type SchemaOptions, type StaticDecode, StringEnum, Value, isObject } from "core/utils";
-import { WhereBuilder, type WhereQuery } from "../entities";
-import * as tbbox from "@sinclair/typebox";
-const { Type } = tbbox;
-
-const NumberOrString = (options: SchemaOptions = {}) =>
-   Type.Transform(Type.Union([Type.Number(), Type.String()], options))
-      .Decode((value) => Number.parseInt(String(value)))
-      .Encode(String);
-
-const limit = NumberOrString({ default: 10 });
-const offset = NumberOrString({ default: 0 });
-
-const sort_default = { by: "id", dir: "asc" };
-const sort = Type.Transform(
-   Type.Union(
-      [Type.String(), Type.Object({ by: Type.String(), dir: StringEnum(["asc", "desc"]) })],
-      {
-         default: sort_default,
-      },
-   ),
-)
-   .Decode((value): { by: string; dir: "asc" | "desc" } => {
-      if (typeof value === "string") {
-         if (/^-?[a-zA-Z_][a-zA-Z0-9_.]*$/.test(value)) {
-            const dir = value[0] === "-" ? "desc" : "asc";
-            return { by: dir === "desc" ? value.slice(1) : value, dir } as any;
-         } else if (/^{.*}$/.test(value)) {
-            return JSON.parse(value) as any;
-         }
-
-         return sort_default as any;
-      }
-      return value as any;
-   })
-   .Encode((value) => value);
-
-const stringArray = Type.Transform(
-   Type.Union([Type.String(), Type.Array(Type.String())], { default: [] }),
-)
-   .Decode((value) => {
-      if (Array.isArray(value)) {
-         return value;
-      } else if (value.includes(",")) {
-         return value.split(",");
-      }
-      return [value];
-   })
-   .Encode((value) => (Array.isArray(value) ? value : [value]));
-
-export const whereSchema = Type.Transform(
-   Type.Union([Type.String(), Type.Object({})], { default: {} }),
-)
-   .Decode((value) => {
-      const q = typeof value === "string" ? JSON.parse(value) : value;
-      return WhereBuilder.convert(q);
-   })
-   .Encode(JSON.stringify);
-
-export type RepoWithSchema = Record<
-   string,
-   Omit<RepoQueryIn, "with"> & {
-      with?: unknown;
-   }
->;
-
-export const withSchema = <TSelf extends TThis>(Self: TSelf) =>
-   Type.Transform(
-      Type.Union([Type.String(), Type.Array(Type.String()), Type.Record(Type.String(), Self)]),
-   )
-      .Decode((value) => {
-         // images
-         // images,comments
-         // ["images","comments"]
-         // { "images": {} }
-
-         if (!Array.isArray(value) && isObject(value)) {
-            return value as RepoWithSchema;
-         }
-
-         let _value: any = null;
-         if (typeof value === "string") {
-            // if stringified object
-            if (value.match(/^\{/)) {
-               return JSON.parse(value) as RepoWithSchema;
-            }
-
-            // if stringified array
-            if (value.match(/^\[/)) {
-               _value = JSON.parse(value) as string[];
-
-               // if comma-separated string
-            } else if (value.includes(",")) {
-               _value = value.split(",");
-
-               // if single string
-            } else {
-               _value = [value];
-            }
-         } else if (Array.isArray(value)) {
-            _value = value;
-         }
-
-         if (!_value || !Array.isArray(_value) || !_value.every((v) => typeof v === "string")) {
-            throw new Error("Invalid 'with' schema");
-         }
-
-         return _value.reduce((acc, v) => {
-            acc[v] = {};
-            return acc;
-         }, {} as RepoWithSchema);
-      })
-      .Encode((value) => value);
-
-export const querySchema = Type.Recursive(
-   (Self) =>
-      Type.Partial(
-         Type.Object(
-            {
-               limit: limit,
-               offset: offset,
-               sort: sort,
-               select: stringArray,
-               with: withSchema(Self),
-               join: stringArray,
-               where: whereSchema,
-            },
-            {
-               // @todo: determine if unknown is allowed, it's ignore anyway
-               additionalProperties: false,
-            },
-         ),
-      ),
-   { $id: "query-schema" },
-);
-
-export type RepoQueryIn = {
-   limit?: number;
-   offset?: number;
-   sort?: string | { by: string; dir: "asc" | "desc" };
-   select?: string[];
-   with?: string | string[] | Record<string, RepoQueryIn>;
-   join?: string[];
-   where?: WhereQuery;
-};
-export type RepoQuery = Required<StaticDecode<typeof querySchema>>;
-export const defaultQuerySchema = Value.Default(querySchema, {}) as RepoQuery;

app/src/data/server/query.spec.ts

@@ -0,0 +1,184 @@
+import { test, describe, expect } from "bun:test";
+import * as q from "./query";
+import { s as schema, parse as $parse, type ParseOptions } from "core/object/schema";
+
+const parse = (v: unknown, o: ParseOptions = {}) => $parse(q.repoQuery, v, o);
+
+// compatibility
+const decode = (input: any, output: any) => {
+   expect(parse(input)).toEqual(output);
+};
+
+describe("server/query", () => {
+   test("limit & offset", () => {
+      expect(() => parse({ limit: false })).toThrow();
+      expect(parse({ limit: "11" })).toEqual({ limit: 11 });
+      expect(parse({ limit: 20 })).toEqual({ limit: 20 });
+      expect(parse({ offset: "1" })).toEqual({ offset: 1 });
+   });
+
+   test("select", () => {
+      expect(parse({ select: "id" })).toEqual({ select: ["id"] });
+      expect(parse({ select: "id,title" })).toEqual({ select: ["id", "title"] });
+      expect(parse({ select: "id,title,desc" })).toEqual({ select: ["id", "title", "desc"] });
+      expect(parse({ select: ["id", "title"] })).toEqual({ select: ["id", "title"] });
+
+      expect(() => parse({ select: "not allowed" })).toThrow();
+      expect(() => parse({ select: "id," })).toThrow();
+   });
+
+   test("join", () => {
+      expect(parse({ join: "id" })).toEqual({ join: ["id"] });
+      expect(parse({ join: "id,title" })).toEqual({ join: ["id", "title"] });
+      expect(parse({ join: ["id", "title"] })).toEqual({ join: ["id", "title"] });
+   });
+
+   test("sort", () => {
+      expect(parse({ sort: "id" }).sort).toEqual({
+         by: "id",
+         dir: "asc",
+      });
+      expect(parse({ sort: "-id" }).sort).toEqual({
+         by: "id",
+         dir: "desc",
+      });
+      expect(parse({ sort: { by: "title" } }).sort).toEqual({
+         by: "title",
+      });
+      expect(
+         parse(
+            { sort: { by: "id" } },
+            {
+               withDefaults: true,
+            },
+         ).sort,
+      ).toEqual({
+         by: "id",
+         dir: "asc",
+      });
+      expect(parse({ sort: { by: "count", dir: "desc" } }).sort).toEqual({
+         by: "count",
+         dir: "desc",
+      });
+      // invalid gives default
+      expect(parse({ sort: "not allowed" }).sort).toEqual({
+         by: "id",
+         dir: "asc",
+      });
+
+      // json
+      expect(parse({ sort: JSON.stringify({ by: "count", dir: "desc" }) }).sort).toEqual({
+         by: "count",
+         dir: "desc",
+      });
+   });
+
+   test("sort2", () => {
+      const _dflt = { sort: { by: "id", dir: "asc" } } as const;
+
+      decode({ sort: "" }, _dflt);
+      decode({ sort: "name" }, { sort: { by: "name", dir: "asc" } });
+      decode({ sort: "-name" }, { sort: { by: "name", dir: "desc" } });
+      decode({ sort: "-posts.name" }, { sort: { by: "posts.name", dir: "desc" } });
+      decode({ sort: "-1name" }, _dflt);
+      decode({ sort: { by: "name", dir: "desc" } }, { sort: { by: "name", dir: "desc" } });
+   });
+
+   test("where", () => {
+      expect(parse({ where: { id: 1 } }).where).toEqual({
+         id: { $eq: 1 },
+      });
+      expect(parse({ where: JSON.stringify({ id: 1 }) }).where).toEqual({
+         id: { $eq: 1 },
+      });
+
+      expect(parse({ where: { count: { $gt: 1 } } }).where).toEqual({
+         count: { $gt: 1 },
+      });
+      expect(parse({ where: JSON.stringify({ count: { $gt: 1 } }) }).where).toEqual({
+         count: { $gt: 1 },
+      });
+   });
+
+   test("template", () => {
+      expect(
+         q.repoQuery.template({
+            withOptional: true,
+         }),
+      ).toEqual({
+         limit: 10,
+         offset: 0,
+         sort: { by: "id", dir: "asc" },
+         where: {},
+         select: [],
+         join: [],
+      });
+   });
+
+   test("with", () => {
+      let example = {
+         limit: 10,
+         with: {
+            posts: { limit: "10", with: ["comments"] },
+         },
+      };
+      expect(parse(example)).toEqual({
+         limit: 10,
+         with: {
+            posts: {
+               limit: 10,
+               with: {
+                  comments: {},
+               },
+            },
+         },
+      });
+
+      decode({ with: ["posts"] }, { with: { posts: {} } });
+      decode({ with: { posts: {} } }, { with: { posts: {} } });
+      decode({ with: { posts: { limit: 1 } } }, { with: { posts: { limit: 1 } } });
+      decode(
+         {
+            with: {
+               posts: {
+                  with: {
+                     images: {
+                        limit: "10",
+                        select: "id",
+                     },
+                  },
+               },
+            },
+         },
+         {
+            with: {
+               posts: {
+                  with: {
+                     images: {
+                        limit: 10,
+                        select: ["id"],
+                     },
+                  },
+               },
+            },
+         },
+      );
+
+      // over http
+      {
+         const output = { with: { images: {} } };
+         decode({ with: "images" }, output);
+         decode({ with: '["images"]' }, output);
+         decode({ with: ["images"] }, output);
+         decode({ with: { images: {} } }, output);
+      }
+
+      {
+         const output = { with: { images: {}, comments: {} } };
+         decode({ with: "images,comments" }, output);
+         decode({ with: ["images", "comments"] }, output);
+         decode({ with: '["images", "comments"]' }, output);
+         decode({ with: { images: {}, comments: {} } }, output);
+      }
+   });
+});

app/src/data/server/query.ts

@@ -0,0 +1,153 @@
+import { s } from "core/object/schema";
+import { WhereBuilder, type WhereQuery } from "data";
+import { $console } from "core";
+import { isObject } from "core/utils";
+import type { CoercionOptions, TAnyOf } from "jsonv-ts";
+
+// -------
+// helpers
+const stringIdentifier = s.string({
+   // allow "id", "id,title" – but not "id," or "not allowed"
+   pattern: "^(?:[a-zA-Z_$][\\w$]*)(?:,[a-zA-Z_$][\\w$]*)*$",
+});
+const stringArray = s.anyOf(
+   [
+      stringIdentifier,
+      s.array(stringIdentifier, {
+         uniqueItems: true,
+      }),
+   ],
+   {
+      default: [],
+      coerce: (v): string[] => {
+         if (Array.isArray(v)) {
+            return v;
+         } else if (typeof v === "string") {
+            if (v.includes(",")) {
+               return v.split(",");
+            }
+            return [v];
+         }
+         return [];
+      },
+   },
+);
+
+// -------
+// sorting
+const sortDefault = { by: "id", dir: "asc" };
+const sortSchema = s.object({
+   by: s.string(),
+   dir: s.string({ enum: ["asc", "desc"] }).optional(),
+});
+type SortSchema = s.Static<typeof sortSchema>;
+const sort = s.anyOf([s.string(), sortSchema], {
+   default: sortDefault,
+   coerce: (v): SortSchema => {
+      if (typeof v === "string") {
+         if (/^-?[a-zA-Z_][a-zA-Z0-9_.]*$/.test(v)) {
+            const dir = v[0] === "-" ? "desc" : "asc";
+            return { by: dir === "desc" ? v.slice(1) : v, dir } as any;
+         } else if (/^{.*}$/.test(v)) {
+            return JSON.parse(v) as any;
+         }
+
+         $console.warn(`Invalid sort given: '${JSON.stringify(v)}'`);
+         return sortDefault as any;
+      }
+      return v as any;
+   },
+});
+
+// ------
+// filter
+const where = s.anyOf([s.string(), s.object({})], {
+   default: {},
+   examples: [
+      {
+         attribute: {
+            $eq: 1,
+         },
+      },
+   ],
+   coerce: (value: unknown) => {
+      const q = typeof value === "string" ? JSON.parse(value) : value;
+      return WhereBuilder.convert(q);
+   },
+});
+//type WhereSchemaIn = s.Static<typeof where>;
+//type WhereSchema = s.StaticCoerced<typeof where>;
+
+// ------
+// with
+// @todo: waiting for recursion support
+export type RepoWithSchema = Record<
+   string,
+   Omit<RepoQueryIn, "with"> & {
+      with?: unknown;
+   }
+>;
+
+const withSchema = <In, Out = In>(self: s.TSchema): s.TSchemaInOut<In, Out> =>
+   s.anyOf([stringIdentifier, s.array(stringIdentifier), self], {
+      coerce: function (this: TAnyOf<any>, _value: unknown, opts: CoercionOptions = {}) {
+         let value: any = _value;
+
+         if (typeof value === "string") {
+            // if stringified object
+            if (value.match(/^\{/) || value.match(/^\[/)) {
+               value = JSON.parse(value);
+            } else if (value.includes(",")) {
+               value = value.split(",");
+            } else {
+               value = [value];
+            }
+         }
+
+         // Convert arrays to objects
+         if (Array.isArray(value)) {
+            value = value.reduce((acc, v) => {
+               acc[v] = {};
+               return acc;
+            }, {} as any);
+         }
+
+         // Handle object case
+         if (isObject(value)) {
+            for (const k in value) {
+               value[k] = self.coerce(value[k], opts);
+            }
+         }
+
+         return value as unknown as any;
+      },
+   }) as any;
+
+// ==========
+// REPO QUERY
+export const repoQuery = s.recursive((self) =>
+   s.partialObject({
+      limit: s.number({ default: 10 }),
+      offset: s.number({ default: 0 }),
+      sort,
+      where,
+      select: stringArray,
+      join: stringArray,
+      with: withSchema<RepoWithSchema>(self),
+   }),
+);
+export const getRepoQueryTemplate = () =>
+   repoQuery.template({
+      withOptional: true,
+   }) as Required<RepoQuery>;
+
+export type RepoQueryIn = {
+   limit?: number;
+   offset?: number;
+   sort?: string | { by: string; dir: "asc" | "desc" };
+   select?: string[];
+   with?: string | string[] | Record<string, RepoQueryIn>;
+   join?: string[];
+   where?: WhereQuery;
+};
+export type RepoQuery = s.StaticCoerced<typeof repoQuery>;