motia 0.7.2-beta.135-685562 → 0.7.2-beta.135-014583

package/dist/cjs/create/templates/generate.js

@@ -40,7 +40,7 @@ const glob_1 = require("glob");
 const generateTemplateSteps = (templateFolder) => {
     return async (rootDir, context) => {
         const templatePath = path.join(__dirname, templateFolder);
-        const files = (0, glob_1.globSync)('**/*', { absolute: false, cwd: templatePath });
+        const files = (0, glob_1.globSync)('**/*', { absolute: false, cwd: templatePath, dot: true });
         try {
             for (const fileName of files) {
                 const filePath = path.join(templatePath, fileName);
@@ -54,7 +54,7 @@ const generateTemplateSteps = (templateFolder) => {
                     (0, fs_1.mkdirSync)(targetDir, { recursive: true });
                 }
                 if ((0, fs_1.statSync)(filePath).isDirectory()) {
-                    const folderPath = path.basename(filePath);
+                    const folderPath = filePath.replace(templatePath, '');
                     (0, fs_1.mkdirSync)(path.join(rootDir, folderPath), { recursive: true });
                     continue;
                 }

package/dist/cjs/create/templates/generate.ts

@@ -8,7 +8,7 @@ export type Generator = (rootDir: string, context: CliContext) => Promise<void>
 export const generateTemplateSteps = (templateFolder: string): Generator => {
   return async (rootDir: string, context: CliContext): Promise<void> => {
     const templatePath = path.join(__dirname, templateFolder)
-    const files = globSync('**/*', { absolute: false, cwd: templatePath })
+    const files = globSync('**/*', { absolute: false, cwd: templatePath, dot: true })
 
     try {
       for (const fileName of files) {
@@ -24,7 +24,7 @@ export const generateTemplateSteps = (templateFolder: string): Generator => {
         }
 
         if (statSync(filePath).isDirectory()) {
-          const folderPath = path.basename(filePath)
+          const folderPath = filePath.replace(templatePath, '')
           mkdirSync(path.join(rootDir, folderPath), { recursive: true })
           continue
         }

package/dist/cjs/create/templates/nodejs/.cursor/architecture/database/database-migration.mdc

@@ -0,0 +1,49 @@
+---
+description: How to configure database migrations in the project
+globs:
+alwaysApply: false
+---
+# Configuring database migrations
+
+When configuring database in the project, create a `knexfile.ts` file in the root of the project.
+
+```typescript
+import type { Knex } from 'knex'
+import * as dotenv from 'dotenv'
+
+dotenv.config({ path: '.env' })
+
+const config: Knex.Config = {
+  client: 'postgresql',
+  connection: {
+    host: process.env.DB_HOST,
+    port: process.env.DB_PORT,
+    database: process.env.DB_NAME,
+    user: process.env.DB_USER,
+    password: process.env.DB_PASS,
+  },
+  pool: {
+    min: 2,
+    max: 10,
+  },
+  migrations: {
+    tableName: 'knex_migrations',
+  },
+}
+
+export default config
+```
+
+## Creating a new migration
+
+Prefix should be timestamp in milliseconds.
+
+```bash
+npm run migrate:make 1727115600000_create_users_table
+```
+
+## Running migrations
+
+```bash
+npm run migrate:latest
+```

package/dist/cjs/create/templates/nodejs/.cursor/architecture/database/database.mdc

@@ -0,0 +1,83 @@
+---
+description: Database connections and queries
+globs: src/repositories/**/*.ts
+alwaysApply: false
+---
+# Database Guide
+
+- Prefer knex to interact with the database
+  - http://npmjs.com/package/knex
+- Use knex migrations to manage database schema changes
+- Do NOT create DB calls directly in steps or services, ALWAYS create a repository file to handle the database calls. Follow DDD principles.
+
+## Add commands to package.json
+
+```json
+{
+  "scripts": {
+    "migrate:up": "knex migrate:latest",
+    "migrate:down": "knex migrate:rollback",
+  }
+}
+```
+
+## Creating base database connection
+
+- When SQL database is used, create a database connection file in the `src/repositories/database.ts` file.
+- All columns in code are cammelCase, however, in the database and in the migration, we use snake_case.
+- Avoid numeric incremental IDs, use UUIDs instead. Make sure to add foreign key with cascade delete when applicable.
+
+```typescript
+import knex, { Knex } from 'knex'
+/**
+ * Create these functions to convert between camelCase and snake_case.
+ * This is important to keep the consistency of the data.
+ */
+import { camelToSnake, snakeToCamelObject } from '../utils/case-conversion'
+
+const isProduction = process.env.NODE_ENV === 'production'
+const isDevelopment = process.env.NODE_ENV === 'development'
+
+// Knex configuration
+const knexConfig: Knex.Config = {
+  client: 'pg',
+  connection: {
+    host: process.env.DB_HOST,
+    port: process.env.DB_PORT,
+    user: process.env.DB_USER,
+    password: process.env.DB_PASSWORD,
+    database: process.env.DB_NAME,
+    ssl: process.env.DB_SSL ? {
+      /** In development, we might use self-signed certs */
+      rejectUnauthorized: isProduction, 
+      /** Add CA certificate if needed */
+      ca: undefined, 
+    } : false,
+  },
+  pool: {
+    min: 2,
+    max: 10,
+    idleTimeoutMillis: 30000,
+  },
+  debug: isDevelopment,
+  wrapIdentifier: (value, origImpl) => origImpl(camelToSnake(value)),
+  postProcessResponse: result => 
+    Array.isArray(result) 
+      ? result.map(row => snakeToCamelObject(row)) 
+      : snakeToCamelObject(result),
+}
+
+// Create a singleton instance
+let db: Knex | null = null
+
+/**
+ * Get the database instance
+ * @returns Knex instance
+ */
+export const getDb = (): Knex => {
+  if (!db) {
+    db = knex(knexConfig)
+  }
+  return db
+}
+```

package/dist/cjs/create/templates/nodejs/src/services/pet-store/create-order.ts.txt

@@ -0,0 +1,15 @@
+import { Order } from './types'
+
+export const createOrder = async (order: Omit<Order, 'id'>): Promise<Order> => {
+  const response = await fetch('https://petstore.swagger.io/v2/store/order', {
+    method: 'POST',
+    body: JSON.stringify({
+      quantity: order?.quantity ?? 1,
+      petId: 1,
+      shipDate: order?.shipDate ?? new Date().toISOString(),
+      status: order?.status ?? 'placed',
+    }),
+    headers: { 'Content-Type': 'application/json' },
+  })
+  return response.json()
+}

package/dist/cjs/create/templates/nodejs/src/services/pet-store/create-pet.ts.txt

@@ -0,0 +1,14 @@
+import { Pet } from './types'
+
+export const createPet = async (pet: Omit<Pet, 'id'>): Promise<Pet> => {
+  const response = await fetch('https://petstore.swagger.io/v2/pet', {
+    method: 'POST',
+    body: JSON.stringify({
+      name: pet?.name ?? '',
+      photoUrls: [pet?.photoUrl ?? ''],
+      status: 'available',
+    }),
+    headers: { 'Content-Type': 'application/json' },
+  })
+  return response.json()
+}

package/dist/cjs/create/templates/nodejs/src/services/pet-store/index.ts.txt

@@ -0,0 +1,9 @@
+import { createPet } from './create-pet'
+import { createOrder } from './create-order'
+
+export * from './types'
+
+export const petStoreService = {
+  createPet,
+  createOrder,
+}

package/dist/{esm/create/templates/nodejs/steps → cjs/create/templates/nodejs/steps/petstore}/api.step.ts-features.json.txt

@@ -4,7 +4,7 @@
     "title": "Step Configuration",
     "description": "All steps should have a defined configuration, this is how you define the step's behavior and how it will be triggered.",
     "lines": [
-      "6-30"
+      "5-29"
     ]
   },
   {
@@ -12,7 +12,7 @@
     "title": "API Step",
     "description": "Definition of an API endpoint",
     "lines": [
-      "12-13"
+      "11-12"
     ]
   },
   {
@@ -20,7 +20,7 @@
     "title": "Request body",
     "description": "Definition of the expected request body. Motia will automatically generate types based on this schema.",
     "lines": [
-      "14-25"
+      "13-24"
     ]
   },
   {
@@ -28,7 +28,7 @@
     "title": "Response Payload",
     "description": "Definition of the expected response payload, Motia will generate the types automatically based on this schema. This is also important to create the Open API spec later.",
     "lines": [
-      "26-28"
+      "25-27"
     ]
   },
   {
@@ -36,8 +36,8 @@
     "title": "Emits",
     "description": "We can define the events that this step will emit, this is how we can trigger other Motia Steps.",
     "lines": [
-      "29",
-      "39-46"
+      "28",
+      "38-45"
     ]
   },
   {
@@ -45,7 +45,7 @@
     "title": "Handler",
     "description": "The handler is the function that will be executed when the step is triggered. This one receives the request body and emits events.",
     "lines": [
-      "32-50"
+      "31-49"
     ]
   },
   {
@@ -53,7 +53,7 @@
     "title": "Logger",
     "description": "The logger is a utility that allows you to log messages to the console. It is available in the handler function. We encourage you to use it instead of console.log. It will automatically be tied to the trace id of the request.",
     "lines": [
-      "33"
+      "32"
     ]
   },
   {
@@ -61,7 +61,7 @@
     "title": "HTTP Response",
     "description": "The handler can return a response to the client. This is how we can return a response to the client. It must comply with the responseSchema defined in the step configuration.",
     "lines": [
-      "49"
+      "48"
     ]
   }
 ]

package/dist/{esm/create/templates/nodejs/steps → cjs/create/templates/nodejs/steps/petstore}/api.step.ts.txt

@@ -1,7 +1,6 @@
 import { ApiRouteConfig, Handlers } from 'motia'
 import { z } from 'zod'
-import { petStoreService } from '../services/pet-store'
-import { petSchema } from '../services/types'
+import { petStoreService, petSchema } from '../../src/services/pet-store'
 
 export const config: ApiRouteConfig = {
   type: 'api',

package/dist/{esm/create/templates/nodejs/steps → cjs/create/templates/nodejs/steps/petstore}/process-food-order.step.ts.txt

@@ -1,6 +1,6 @@
 import { EventConfig, Handlers } from 'motia'
 import { z } from 'zod'
-import { petStoreService } from '../services/pet-store'
+import { petStoreService } from '../../src/services/pet-store'
 
 export const config: EventConfig = {
   type: 'event',

package/dist/cjs/cursor-rules/dot-files/.cursor/architecture/architecture.mdc

@@ -0,0 +1,96 @@
+---
+description: How to structure your Motia project
+globs:
+alwaysApply: true
+---
+
+# Architecture Guide
+
+## Overview
+
+This guide covers the architecture of a Motia project.
+
+## File Structure
+
+All step files should be underneath the `steps/` folder.
+
+Underneath the `steps/` folder, create subfolders for Flows. Flows are used to group steps together.
+
+## Step Naming Conventions
+
+### Typescript
+
+- Use kebab-case for filenames: `resource-processing.step.ts`
+- Include `.step` before language extension
+
+### Python
+
+- Use snake_case for filenames: `data_processor_step.py`
+- Include `_step` before language extension
+
+### Global
+
+- Match handler names to config names
+- Use descriptive, action-oriented names
+
+## Code Style Guidelines
+
+- **JavaScript**: Use modern ES6+ features, async/await, proper error handling
+- **TypeScript**: Make sure you use the correct Handlers type that is auto generated on the `types.d.ts` file.
+
+## Defining Middlewares
+
+Middleware is a powerful feature in Motia to help adding common validation, error
+handling and other common logic to your steps.
+
+- Make sure to add all the middlewares in a single folder, called `middlewares/`.
+- Create a comprehensive file name for the middleware, like `auth.middleware.ts`.
+- Follow SOLID principles with separation of concerns in middlewares, create a middleware for each responsibility.
+- Use core middleware to handle ZodError gracefully (see [Error Handling Guide](./error-handling.mdc))
+- Rate limiting and CORS are not needed to be handled in middleware since they're an infrastructure concern.
+
+## Domain Driven Design
+
+Make sure you follow Domain Driven Design principles in your project.
+
+- Create `/src/services` folder to store your services, this is where it holds business logic.
+- Create `/src/repositories` folder to store your repositories, this is where it holds data access logic.
+- Create `/src/utils` folder to store your utility functions.
+- Models and DTOs are not quite necessary, we can rely on zod to create the models and DTOs from the steps.
+- Controller layer is the Steps, it should have mostly logic around validation and calling services.
+- Avoid having Service methods with just a call to the Repository, it should have some logic around it, if it doesn't have, then Steps can have access to repositories directly.
+
+### Services
+
+Defining services can be done in the following way:
+
+- Create a folder underneath `/src/services/` folder, like `/src/services/auth/`.
+- Create a file inside the folder called `index.ts`.
+- Inside `index.ts`, export a constant with the name of the service, with the methods as properties.
+- Methods should be defined as separate files, use export named functions.
+- Use the service in the Steps.
+
+#### Example
+
+```typescript
+/**
+ * Business logic for authentication defined in a separate file in the same folder.
+ */
+import { login } from './login'
+
+/**
+ * Constant with the name of the service, with the methods as properties.
+ */
+export const authService = {
+  login
+}
+```
+
+## Logging and observability
+
+- Make sure to use the Logger from Motia (from context object) to log messages.
+- Make sure to have visibility of what is going on in a request
+- Before throwing errors, make sure to log the issue, identify if issue is a validation blocker, then log with `logger.warn`, if it's something that is not supposed to happen, then log with `logger.error`.
+- Make sure to add context to the logs to help identify any potential issues.
+
+

package/dist/cjs/cursor-rules/dot-files/.cursor/architecture/error-handling.mdc

@@ -0,0 +1,122 @@
+---
+description: How to handle errors in a Motia project
+globs:
+alwaysApply: true
+---
+
+# Error Handling Guide
+
+Errors happen, but we need to handle them gracefully. Make sure you create a custom error class for your project, underneath `/src/errors/` folder.
+
+## Good practices
+
+- Use Custom error to return errors to the client.
+- Anything that is not the error class, should be logged with `logger.error`. And root cause should be omitted to the client.
+
+## Create a custom Error class
+
+Name: `/src/errors/base.error.ts`
+
+```typescript
+export class BaseError extends Error {
+  public readonly status: number
+  public readonly code: string
+  public readonly metadata: Record<string, any>
+
+  constructor(
+    message: string,
+    status: number = 500,
+    code: string = 'INTERNAL_SERVER_ERROR',
+    metadata: Record<string, any> = {}
+  ) {
+    super(message)
+    this.name = this.constructor.name
+    this.status = status
+    this.code = code
+    this.metadata = metadata
+
+    // Maintains proper stack trace for where our error was thrown
+    Error.captureStackTrace(this, this.constructor)
+  }
+
+  toJSON() {
+    return {
+      error: {
+        name: this.name,
+        message: this.message,
+        code: this.code,
+        status: this.status,
+        ...(Object.keys(this.metadata).length > 0 && { metadata: this.metadata }),
+      },
+    }
+  }
+}
+```
+
+Then create sub class for specific errors that are commonly thrown in your project.
+
+Name: `/src/errors/not-found.error.ts`
+
+```typescript
+import { BaseError } from './base.error'
+
+export class NotFoundError extends BaseError {
+  constructor(message: string = 'Not Found', metadata: Record<string, any> = {}) {
+    super(message, 404, 'NOT_FOUND', metadata)
+  }
+}
+```
+
+## Core Middleware
+
+Make sure you create a core middleware that will be added to ALL API Steps.
+
+File: `/src/middlewares/core.middleware.ts`
+
+```typescript
+import { ApiMiddleware } from 'motia'
+import { ZodError } from 'zod'
+import { BaseError } from '../errors/base.error'
+
+export const coreMiddleware: ApiMiddleware = async (req, ctx, next) => {
+  const logger = ctx.logger
+
+  try {
+    return await next()
+  } catch (error: any) {
+    if (error instanceof ZodError) {
+      logger.error('Validation error', {
+        error,
+        stack: error.stack,
+        errors: error.errors,
+      })
+
+      return {
+        status: 400,
+        body: {
+          error: 'Invalid request body',
+          data: error.errors,
+        },
+      }
+    } else if (error instanceof BaseError) {
+      logger.error('BaseError', {
+        status: error.status,
+        code: error.code,
+        metadata: error.metadata,
+        name: error.name,
+        message: error.message,
+      })
+
+      return { status: error.status, body: error.toJSON() }
+    }
+
+    logger.error('Error while performing request', {
+      error,
+      body: req.body,
+      stack: error.stack,
+    })
+
+    return { status: 500, body: { error: 'Internal Server Error' } }
+  }
+}
+```

package/dist/cjs/cursor-rules/dot-files/.cursor/index.mdc

@@ -0,0 +1,26 @@
+---
+description: Rules for the project
+globs:
+alwaysApply: true
+---
+
+## Adding migration
+
+Make sure to use [migration guide](./architecture/database/database-migration.mdc) to create a new migration.
+
+## Database integration
+
+Whenever database is used, please use [database guide](./architecture/database/database.mdc) to create a database connection and methods.
+
+## Real time events
+
+Make sure to use [real time events guide](./rules/motia/realtime-streaming.mdc) to create a new real time event.
+
+## State/Cache management
+
+Make sure to use [state management guide](./rules/motia/state-management.mdc) to create a new state management.
+
+## Authentication
+
+If ever need to add authentication, make sure to use middleware to authenticate the request.
+Make sure to use [middlewares](./rules/motia/middlewares.mdc) to validate the requests.