@process.co/element-types 0.0.1-docs

package/.github/README.md

@@ -0,0 +1,22 @@
+# Internal Developer Notes: Element Types
+
+This package contains shared types and utilities for Process.co elements.
+
+- **Source:** Monorepo: [`process-co/proc-app/process-co/element-types`](https://github.com/process-co/proc-app/tree/main/process-co/element-types)
+- **Publish Repo:** `process-co/npm-element-types`
+- **Published to:** [npm](https://www.npmjs.com/package/@process.co/element-types)
+- **Sync workflow:** See [`.github/workflows/sync-element-types.yml`](https://github.com/process-co/proc-app/blob/main/.github/workflows/sync%20-%20element-types.yml) 
+
+> [!IMPORTANT] 
+> CHANGES HERE WILL GET OVERWRITTEN
+> The JS code in this repo is published from the proc-app mono repo located at https://github.com/process-co/proc-app/tree/main/process-co/element-types, the publish process bundles the specific parts of our (monorepo) internal libararies needed to run the element validataion actions
+
+> [!WARNING] 
+> NOTHING IS MANAGED IN THIS REPO
+> this repo is only publishing to break out code that is part of a mono repo
+
+
+## Contribution
+All changes should be made in the [`https://github.com/process-co/proc-app/process-co/element-types`](https://ghttps://github.com/process-co/proc-app/tree/main/process-co/element-types) 
+
+Contact @process-dev for questions. 

package/.github/workflows/publish-element-types.yml

@@ -0,0 +1,71 @@
+name: Publish Element Types
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      registry:
+        description: 'NPM Registry URL'
+        required: false
+        type: string
+        default: 'https://registry.npmjs.org'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          registry-url: ${{ github.event.inputs.registry || 'https://registry.npmjs.org' }}
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 10
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Get version from tag
+        id: get_version
+        run: |
+          if [[ "${{ github.event_name }}" == "release" ]]; then
+            VERSION=${GITHUB_REF#refs/tags/}
+            VERSION=${VERSION#v}
+          else
+            VERSION=$(node -p "require('./package.json').version")
+          fi
+          echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
+          echo "Using version: $VERSION"
+
+      - name: Update version in package.json
+        run: |
+          sed -i 's/"version": "[^"]*"/"version": "${{ steps.get_version.outputs.VERSION }}"/' package.json
+          REGISTRY="${{ github.event.inputs.registry || 'https://registry.npmjs.org' }}"
+          jq --arg reg "$REGISTRY" '.publishConfig.registry = $reg | .registry = $reg' package.json > package.json.tmp && mv package.json.tmp package.json
+          jq '.publishConfig.access = "public"' package.json > package.json.tmp && mv package.json.tmp package.json
+
+      - name: Verify package structure
+        run: |
+          echo "Checking package structure..."
+          [ -d "dist" ] || (echo "Error: dist directory missing!" && exit 1)
+          [ -f "dist/index.js" ] || (echo "Error: dist/index.js missing!" && exit 1)
+          [ -f "dist/index.d.ts" ] || (echo "Error: dist/index.d.ts missing!" && exit 1)
+          echo "dist/index.js and dist/index.d.ts found."
+          echo "Final package.json:"
+          cat package.json
+
+      - name: Publish to npm
+        run: pnpm publish --access=public --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_REGISTRY: ${{ github.event.inputs.registry || 'https://registry.npmjs.org' }} 

package/README.md

@@ -0,0 +1,60 @@
+# @process.co/element-types ![NPM Version](https://img.shields.io/npm/v/%40process.co%2Felement-types) ![GitHub Release](https://img.shields.io/github/v/release/process-co/npm-element-types) ![GitHub package.json version (branch)](https://img.shields.io/github/package-json/v/process-co/npm-element-types/main?color=%23AA00AA)
+
+
+
+
+
+TypeScript types and utilities for defining Process.co Elements.
+
+## Installation
+
+```bash
+npm install @process.co/element-types
+```
+
+### Pinned Version
+```bash
+npm install git+https://github.com/process-co/npm-element-types.git#v0.0.1
+```
+
+### Latest Development Version
+```bash
+npm install git+https://github.com/process-co/npm-element-types.git#main
+```
+
+## Usage
+
+```typescript
+import { defineApp } from '@process.co/element-types';
+
+// Define the app
+const exampleApp = defineApp({
+  type: "app",
+  app: "example_app",
+  props: {
+    someProp: {
+      label: "Some Prop",
+      description: "This is some prop",
+      type: "string",
+    },
+  } as const,
+  methods: {
+    async doSomthing(this: DeriveAppInstance<ExampleApp>, $: any, switchExpression: string, cases: Record<string, unknown>) {
+      // Implementation
+      return {};
+    },
+    // ... other methods
+  },
+});
+
+// Derive types from the implementation
+export type ExampleApp = typeof exampleApp;
+export type ExampleAppInstance = DeriveAppInstance<ExampleApp>;
+
+export default processInternalApp;
+
+```
+
+## License
+
+MIT 

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+export type ElementString = {
+    type: "string";
+    label?: string;
+    description?: string;
+};
+export type ElementObject = {
+    type: "object";
+    label?: string;
+    description?: string;
+};
+export type ElementNumber = {
+    type: "number";
+    label?: string;
+    description?: string;
+};
+export type ElementBoolean = {
+    type: "boolean";
+    label?: string;
+    description?: string;
+};
+export type ElementApp<T> = {
+    type: "app";
+    app: T;
+};
+export type ModuleDefinition = {
+    type: string;
+    app: string;
+    propDefinitions: Record<string, unknown>;
+    methods: Record<string, (params: any) => Promise<unknown>>;
+};
+export type PropType<T> = T extends {
+    props: Record<string, any>;
+    methods: Record<string, any>;
+} ? DeriveAppInstance<T> : T extends {
+    type: "string";
+} ? string : T extends {
+    type: "object";
+} ? Record<string, unknown> : T extends {
+    type: "number";
+} ? number : T extends {
+    type: "boolean";
+} ? boolean : unknown;
+export type ModuleShape = {
+    type: string;
+    props: Record<string, any>;
+    methods: Record<string, any>;
+};
+export type Spread<T> = {
+    [K in keyof T]: T[K];
+};
+export type DeriveAppInstance<T> = T extends {
+    methods: Record<string, any>;
+    props: Record<string, any>;
+} ? Spread<Omit<T, "props" | "methods"> & {
+    [K in keyof T["props"]]: PropType<T["props"][K]>;
+} & {
+    [K in keyof T["methods"]]: T["methods"][K];
+}> : never;
+export type DeriveActionInstance<T> = T extends {
+    methods: Record<string, any>;
+    props: Record<string, any>;
+} ? Spread<Omit<T, "props" | "methods"> & {
+    [K in keyof T["props"]]: T["props"][K] extends {
+        type: string;
+    } ? PropType<T["props"][K]> : T["props"][K] extends {
+        type: "app";
+        methods: Record<string, any>;
+    } ? {
+        [M in keyof T["props"][K]["methods"]]: T["props"][K]["methods"][M];
+    } : T["props"][K] extends {
+        methods: Record<string, any>;
+        props: Record<string, any>;
+    } ? DeriveActionInstance<T["props"][K]> : T["props"][K];
+} & {
+    [K in keyof T["methods"]]: T["methods"][K];
+}> : never;
+export type ModuleWithThis<T> = T & ThisType<DeriveActionInstance<T>>;
+export interface Action<P extends Record<string, any> = Record<string, any>> extends ModuleDefinition {
+    type: "action";
+    props: P;
+    run: (this: DeriveActionInstance<Action<P>>, params: {
+        $: any;
+    }) => Promise<unknown>;
+}
+export type ActionInstance<A extends Action> = DeriveActionInstance<A>;
+export type ActionMethod<A extends Action> = (this: ActionInstance<A>, params: {
+    $: any;
+}) => Promise<unknown>;
+export type PropDefinition = {
+    label: string;
+    description: string;
+    type: string;
+    ui?: any;
+};
+export declare function defineApp<T extends object>(app: T & ThisType<DeriveAppInstance<T>>): T;
+export declare function defineAction<T extends object>(action: T & ThisType<DeriveActionInstance<T>>): T;
+export type WithThis<T> = T extends {
+    methods: Record<string, any>;
+    props: Record<string, any>;
+} ? Omit<T, 'methods'> & {
+    methods: {
+        [K in keyof T['methods']]: T['methods'][K] extends (...args: infer A) => infer R ? (this: DeriveActionInstance<T>, ...args: A) => R : T['methods'][K];
+    };
+} : T;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACrF,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACrF,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACrF,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACvF,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,CAAC,CAAA;CAAE,CAAC;AAGpD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;CAC5D,CAAC;AAGF,MAAM,MAAM,QAAQ,CAAC,CAAC,IACpB,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,GAClE,iBAAiB,CAAC,CAAC,CAAC,GACpB,CAAC,SAAS;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,MAAM,GACrC,CAAC,SAAS;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtD,CAAC,SAAS;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,MAAM,GACrC,CAAC,SAAS;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG,OAAO,GACvC,OAAO,CAAC;AAGd,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B,CAAC;AAGF,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAGjD,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC7B,CAAC,SAAS;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,GAClE,MAAM,CACJ,IAAI,CAAC,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,GAC5B;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACpD;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;CAAE,CAC/C,GACD,KAAK,CAAC;AAGZ,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAChC,CAAC,SAAS;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,GAClE,MAAM,CACJ,IAAI,CAAC,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,GAC5B;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAC7D,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GACvB,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,GACjE;SAAG,CAAC,IAAI,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;KAAE,GACtE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,GAChF,oBAAoB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GACnC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CACpB,GACD;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;CAAE,CAC/C,GACD,KAAK,CAAC;AAGZ,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;AAGtE,MAAM,WAAW,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAE,SAAQ,gBAAgB;IACnG,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,CAAC,CAAC;IACT,GAAG,EAAE,CAAC,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE;QAAE,CAAC,EAAE,GAAG,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACtF;AAED,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI,oBAAoB,CAAC,CAAC,CAAC,CAAC;AAEvE,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE;IAAE,CAAC,EAAE,GAAG,CAAA;CAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAG/G,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,GAAG,CAAC;CACV,CAAC;AAGF,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAEtF;AAGD,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAE/F;AAGD,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,GAC5F,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG;IACrB,OAAO,EAAE;SACN,CAAC,IAAI,MAAM,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,GAC9E,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,GAChD,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;KAClB,CAAC;CACH,GACC,CAAC,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineApp = defineApp;
+exports.defineAction = defineAction;
+// Helper to provide ThisType context for app definitions
+function defineApp(app) {
+    return app;
+}
+// Helper to provide ThisType context for action definitions
+function defineAction(action) {
+    return action;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7QUFxRkEsOEJBRUM7QUFHRCxvQ0FFQztBQVJELHlEQUF5RDtBQUN6RCxTQUFnQixTQUFTLENBQW1CLEdBQXVDO0lBQ2pGLE9BQU8sR0FBRyxDQUFDO0FBQ2IsQ0FBQztBQUVELDREQUE0RDtBQUM1RCxTQUFnQixZQUFZLENBQW1CLE1BQTZDO0lBQzFGLE9BQU8sTUFBTSxDQUFDO0FBQ2hCLENBQUMifQ==

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@process.co/element-types",
+  "version": "0.0.1-docs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/process-co/npm-element-types.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "scope": "@process.co"
+  },
+  "keywords": [
+    "process",
+    "element",
+    "types",
+    "validation"
+  ],
+  "author": {
+    "name": "Process.co Team",
+    "email": "developers@process.co"
+  },
+  "license": "ISC",
+  "registry": "https://registry.npmjs.org",
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/index.ts

@@ -0,0 +1,104 @@
+// Element types
+export type ElementString = { type: "string"; label?: string; description?: string };
+export type ElementObject = { type: "object"; label?: string; description?: string };
+export type ElementNumber = { type: "number"; label?: string; description?: string };
+export type ElementBoolean = { type: "boolean"; label?: string; description?: string };
+export type ElementApp<T> = { type: "app"; app: T };
+
+// Base types for module definitions
+export type ModuleDefinition = {
+  type: string;
+  app: string;
+  propDefinitions: Record<string, unknown>;
+  methods: Record<string, (params: any) => Promise<unknown>>;
+};
+
+// Utility type for transforming prop definitions to their runtime types
+export type PropType<T> =
+  T extends { props: Record<string, any>; methods: Record<string, any> }
+    ? DeriveAppInstance<T>
+    : T extends { type: "string" } ? string
+    : T extends { type: "object" } ? Record<string, unknown>
+    : T extends { type: "number" } ? number
+    : T extends { type: "boolean" } ? boolean
+    : unknown;
+
+// Base module shape type
+export type ModuleShape = {
+  type: string;
+  props: Record<string, any>;
+  methods: Record<string, any>;
+};
+
+// Utility type to force flattening of intersections
+export type Spread<T> = { [K in keyof T]: T[K] };
+
+// Helper type to derive instance type from app definition, fully flattened
+export type DeriveAppInstance<T> =
+  T extends { methods: Record<string, any>; props: Record<string, any> }
+    ? Spread<
+        Omit<T, "props" | "methods"> &
+        { [K in keyof T["props"]]: PropType<T["props"][K]> } &
+        { [K in keyof T["methods"]]: T["methods"][K] }
+      >
+    : never;
+
+// Helper type to derive instance type from action/source definition, fully flattened
+export type DeriveActionInstance<T> =
+  T extends { methods: Record<string, any>; props: Record<string, any> }
+    ? Spread<
+        Omit<T, "props" | "methods"> &
+        { [K in keyof T["props"]]: T["props"][K] extends { type: string }
+          ? PropType<T["props"][K]>
+          : T["props"][K] extends { type: "app"; methods: Record<string, any> }
+            ? { [M in keyof T["props"][K]["methods"]]: T["props"][K]["methods"][M] }
+            : T["props"][K] extends { methods: Record<string, any>; props: Record<string, any> }
+              ? DeriveActionInstance<T["props"][K]>
+              : T["props"][K]
+        } &
+        { [K in keyof T["methods"]]: T["methods"][K] }
+      >
+    : never;
+
+// Helper type to create a module with proper this context
+export type ModuleWithThis<T> = T & ThisType<DeriveActionInstance<T>>;
+
+// Action-specific types
+export interface Action<P extends Record<string, any> = Record<string, any>> extends ModuleDefinition {
+  type: "action";
+  props: P;
+  run: (this: DeriveActionInstance<Action<P>>, params: { $: any }) => Promise<unknown>;
+}
+
+export type ActionInstance<A extends Action> = DeriveActionInstance<A>;
+
+export type ActionMethod<A extends Action> = (this: ActionInstance<A>, params: { $: any }) => Promise<unknown>;
+
+// Prop definition type
+export type PropDefinition = {
+  label: string;
+  description: string;
+  type: string;
+  ui?: any;
+};
+
+// Helper to provide ThisType context for app definitions
+export function defineApp<T extends object>(app: T & ThisType<DeriveAppInstance<T>>): T {
+  return app;
+}
+
+// Helper to provide ThisType context for action definitions
+export function defineAction<T extends object>(action: T & ThisType<DeriveActionInstance<T>>): T {
+  return action;
+}
+
+// Utility type to automatically infer the correct this context for methods
+export type WithThis<T> = T extends { methods: Record<string, any>; props: Record<string, any> }
+  ? Omit<T, 'methods'> & {
+    methods: {
+      [K in keyof T['methods']]: T['methods'][K] extends (...args: infer A) => infer R
+      ? (this: DeriveActionInstance<T>, ...args: A) => R
+      : T['methods'][K];
+    };
+  }
+  : T;