feat: Add helper functions for defining entries, settings, extension and api actions (#37)

Author: eveffer

cli/incloud.ts

@@ -34,16 +34,30 @@ function parseArgs() {
 }
 
 function makeMainFile(projectName: string) {
-  const mainfile = `import { createInCloud } from "@inspatial/cloud";
+  const mainfile =
+    `import { createInCloud, defineExtension, defineEntry } from "@inspatial/cloud";
 
-createInCloud({
-  name: "${projectName}",
-  description: "My InCloud Project",
-  entryTypes: [], // Define your entry types here
-  settingsTypes: [], // Define your settings types here
-  actionGroups: [], // Define your API action groups here
+const myEntry = defineEntry("myEntry",{
+  label: "My Entry",
+  description: "A sample entry type",
+  titleField: "name",
+  fields: [{
+    key: "name",
+    type: "DataField",
+    required: true,
+  }]
 });
 
+const myExtension = defineExtension("myExtension",{
+  label: "My Extension",
+  description: "A sample extension",
+  entryTypes: [myEntry],
+  settingsTypes: [],
+  actionGroups: [],
+});
+
+createInCloud("${projectName}", [myExtension]);
+
 `;
   return mainfile;
 }

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@inspatial/cloud",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "license": "Apache-2.0",
   "exports": {
     ".": "./mod.ts",

mod.ts

@@ -18,12 +18,14 @@ export {
   ChildEntryList,
   ChildEntryType,
 } from "~/orm/child-entry/child-entry.ts";
-export { CloudAPIAction } from "~/api/cloud-action.ts";
-export { CloudAPIGroup } from "~/api/cloud-group.ts";
-export { CloudExtension } from "~/extension/cloud-extension.ts";
+export { CloudAPIAction, defineAPIAction } from "~/api/cloud-action.ts";
+export { CloudAPIGroup, defineAPIGroup } from "~/api/cloud-group.ts";
+export {
+  CloudExtension,
+  defineExtension,
+} from "~/extension/cloud-extension.ts";
 
 export { MimeTypes };
-
 export * from "~/orm/mod.ts";
 
 export const utils = {

src/api/api-types.ts

@@ -1,4 +1,4 @@
-import type { InField } from "~/orm/field/field-def-types.ts";
+import type { InField, InFieldType } from "~/orm/field/field-def-types.ts";
 import type { InValue } from "~/orm/field/types.ts";
 
 /**
@@ -62,16 +62,17 @@ export interface CloudAPIActionDocs {
 /**
  * A typed map of parameters passed to an action handler.
  */
-export type CloudParam<P extends PropertyKey> = Omit<InField, "key"> & {
+export type CloudParam<
+  P extends PropertyKey,
+> = {
   key: P;
-};
+} & InField;
 /**
  * A typed map of required parameters passed to an action handler.
  */
 
 export type ExtractParams<
-  K extends PropertyKey,
-  P extends Array<CloudParam<K>>,
+  P extends Array<InField>,
 > =
   & {
     [S in P[number] as S["required"] extends true ? S["key"] : never]: InValue<

src/api/cloud-action.ts

@@ -9,37 +9,35 @@ import type { SessionData } from "~/auth/types.ts";
 import type { InCloud } from "~/in-cloud.ts";
 
 export type ActionMethod<
-  K extends PropertyKey = PropertyKey,
-  P extends Array<CloudParam<K>> = Array<CloudParam<K>>,
-> = (args: {
+  P extends Array<InField> | undefined = undefined,
+> = (
+  args: P extends undefined ? ActionMethodNoParams : {
+    inCloud: InCloud;
+    orm: InSpatialORM;
+    params: P extends Array<infer F> ? ExtractParams<P> : never;
+    inRequest: InRequest;
+    inResponse: InResponse;
+  },
+) => Promise<any> | any;
+
+type ActionMethodNoParams = {
   inCloud: InCloud;
   orm: InSpatialORM;
-  params: ExtractParams<K, P>;
   inRequest: InRequest;
   inResponse: InResponse;
-}) => Promise<any> | any;
-
-export type ActionConfig<
-  K extends PropertyKey = PropertyKey,
-  P extends Array<CloudParam<K>> = Array<CloudParam<K>>,
-  R extends ActionMethod<K, P> = ActionMethod<K, P>,
-> = {
-  run: R;
-  /**
-   * Whether to skip reading the request body. Should be set to true if the action
-   * will be reading the request body itself, such as when uploading files.
-   */
-  raw?: boolean;
-  description?: string;
+};
+
+export interface ActionConfigBase {
   label?: string;
+  description?: string;
+  raw?: boolean;
   authRequired?: boolean;
   hideFromApi?: boolean;
-  params: P;
-};
+}
+
 export class CloudAPIAction<
-  K extends PropertyKey = PropertyKey,
-  P extends Array<CloudParam<K>> = Array<CloudParam<K>>,
-  R extends ActionMethod<K, P> = ActionMethod<K, P>,
+  K extends string = string,
+  AP extends Array<InField & { key: K }> | undefined = any,
 > {
   description: string = "This is a Cloud API action";
   label?: string;
@@ -52,23 +50,20 @@ export class CloudAPIAction<
   params: Map<string, CloudParam<PropertyKey>>;
   requiredParams: string[] = [];
 
-  #_run: (args: {
-    inCloud: InCloud;
-    orm: InSpatialORM;
-    params: any;
-    inRequest: InRequest;
-    inResponse: InResponse;
-  }) => Promise<any> | any;
+  #_run: ActionMethod<AP>;
 
   raiseError(message: string): never {
     raiseServerException(400, message);
   }
 
   constructor(
     actionName: string,
-    config: ActionConfig<K, P, R>,
+    config: ActionConfigBase & {
+      params?: AP extends undefined ? never : AP;
+      action: ActionMethod<AP>;
+    },
   ) {
-    this.#_run = config.run;
+    this.#_run = config.action;
     this.actionName = actionName;
     this.raw = config.raw || false;
     this.label = config.label || this.label ||
@@ -80,10 +75,10 @@ export class CloudAPIAction<
     if (config.hideFromApi === true) {
       this.includeInAPI = false;
     }
-    this.params = new Map(config.params.map((p) => [p.key as string, p]));
-    this.requiredParams = config.params.filter((param) => param.required).map(
+    this.params = new Map(config.params?.map((p) => [p.key as string, p]));
+    this.requiredParams = config.params?.filter((param) => param.required).map(
       (p) => p.key as string,
-    );
+    ) || [];
   }
 
   #validateParams(
@@ -186,6 +181,25 @@ export class CloudAPIAction<
       runObject.orm = args.inCloud.orm.withUser(user);
     }
 
-    return await this.#_run(runObject);
+    return await this.#_run(runObject as any);
   }
 }
+
+/** Define a Cloud API Action
+ *
+ * @param actionName The name of the action
+ * @param config The configuration for the action
+ * @returns A new CloudAPIAction instance
+ */
+export function defineAPIAction<
+  K extends string,
+  AP extends Array<InField & { key: K }> | undefined,
+>(
+  actionName: string,
+  config: ActionConfigBase & {
+    params?: AP extends undefined ? never : AP;
+    action: ActionMethod<AP>;
+  },
+): CloudAPIAction<K, AP> {
+  return new CloudAPIAction(actionName, config);
+}

src/api/cloud-api.ts

@@ -100,7 +100,7 @@ export class CloudAPI {
       label: "Get Docs",
       description: "Get API documentation",
       params: [],
-      run({ inCloud, inRequest }) {
+      action({ inCloud, inRequest }) {
         const user = inRequest.context.get<SessionData>("user");
         if (!user) {
           return;
@@ -142,7 +142,7 @@ export class CloudAPI {
       description: "Ping the server",
       authRequired: false,
       params: [],
-      run({ inCloud }) {
+      action({ inCloud }) {
         return {
           message: "pong",
           timestamp: Date.now(),

src/api/cloud-group.ts

@@ -1,10 +1,11 @@
 import {
-  type ActionConfig,
+  type ActionConfigBase,
   type ActionMethod,
   CloudAPIAction,
 } from "~/api/cloud-action.ts";
-import type { CloudParam } from "~/api/api-types.ts";
 import { raiseServerException } from "~/serve/server-exception.ts";
+import convertString from "../utils/convert-string.ts";
+import type { InField } from "../orm/field/field-def-types.ts";
 
 export class CloudAPIGroup<
   G extends string = string,
@@ -23,7 +24,7 @@ export class CloudAPIGroup<
     this.description = config.description;
     this.label = config.label;
     this.actions = new Map();
-    config.actions?.forEach((action) => this.addAction(action));
+    config.actions?.forEach((action) => this.#addAction(action));
   }
   #addAction(action: CloudAPIAction) {
     if (this.actions.has(action.actionName)) {
@@ -35,31 +36,41 @@ export class CloudAPIGroup<
     action.groupName = this.groupName;
     this.actions.set(action.actionName, action);
   }
+  /** Add a new action to the group
+   *
+   * @param actionName The name of the action
+   * @param config The configuration for the action
+   */
   addAction<
-    K extends PropertyKey = PropertyKey,
-    P extends Array<CloudParam<K>> = Array<CloudParam<K>>,
-    R extends ActionMethod<K, P> = ActionMethod<K, P>,
-  >(name: string, config: ActionConfig<K, P, R>): void;
-  addAction(action: CloudAPIAction): void;
-  addAction(
-    nameOrAction: string | CloudAPIAction,
-    actionConfig?: ActionConfig,
+    K extends string,
+    AP extends Array<InField & { key: K }> | undefined,
+  >(
+    actionName: string,
+    config: ActionConfigBase & {
+      params?: AP extends undefined ? never : AP;
+      action: ActionMethod<AP>;
+    },
   ): void {
-    if (nameOrAction instanceof CloudAPIAction) {
-      this.#addAction(nameOrAction);
-      return;
-    }
-    if (typeof nameOrAction !== "string") {
-      raiseServerException(400, "action name must be a string");
-    }
-    if (actionConfig === undefined) {
-      raiseServerException(
-        400,
-        `Please provide config options for ${nameOrAction} action`,
-      );
-    }
-
-    const action = new CloudAPIAction(nameOrAction, actionConfig);
+    const action = new CloudAPIAction(actionName, config);
     this.#addAction(action);
   }
 }
+
+/** Define a new API group
+ *
+ * @param groupName The name of the group
+ * @param config The configuration for the group
+ * @returns The defined API group
+ */
+export function defineAPIGroup<G extends string>(groupName: G, config?: {
+  description?: string;
+  label?: string;
+  actions?: Array<CloudAPIAction<any, any>>;
+}): CloudAPIGroup<G> {
+  const group = new CloudAPIGroup(groupName, {
+    description: config?.description || "",
+    label: config?.label || convertString(groupName, "title", true),
+    actions: config?.actions,
+  });
+  return group;
+}

src/auth/actions/auth-check.ts

@@ -2,7 +2,7 @@ import { CloudAPIAction } from "~/api/cloud-action.ts";
 
 const authCheck = new CloudAPIAction("authCheck", {
   description: "Check if user is authenticated",
-  run({ inRequest }) {
+  action({ inRequest }) {
     const user = inRequest.context.get("user");
 
     return user;

src/auth/actions/get-account.ts

@@ -3,7 +3,7 @@ import type { SessionData } from "../types.ts";
 
 export const getAccount = new CloudAPIAction("getAccount", {
   description: "Gets the account for the current authenticated user",
-  async run({ inRequest, inCloud }) {
+  async action({ inRequest, inCloud }) {
     const user = inRequest.context.get<SessionData>("user");
     if (!user || !user.accountId) {
       return;

src/auth/actions/google/google-auth-callback.ts

@@ -8,7 +8,7 @@ import { handleGoogleSignup } from "./handle-google-signup.ts";
 const googleAuthCallback = new CloudAPIAction("googleAuthCallback", {
   authRequired: false,
   description: "Google OAuth2 callback",
-  async run({ inCloud, orm, inRequest, inResponse, params }) {
+  async action({ inCloud, orm, inRequest, inResponse, params }) {
     const { code, state } = params;
     const authSettings = await orm.getSettings(
       "authSettings",