0
# Component Structure
1

2
Core interfaces and types for defining Pipedream components, including the main component interface, app definitions, and lifecycle hooks.
3

4
## Capabilities
5

6
### PipedreamComponent Interface
7

8
The main interface for defining a Pipedream component with all required and optional properties.
9

10
```typescript { .api }
11
/**
12
 * Main interface for defining a Pipedream component
13
 */
14
interface PipedreamComponent {
15
  /** Unique identifier for the component (optional) */
16
  key?: string;
17
  /** Display name for the component (required) */
18
  name: string;
19
  /** Semantic version of the component (required) */
20
  version: string;
21
  /** Description of what the component does (optional) */
22
  description?: string;
23
  /** Component properties configuration (required) */
24
  props: ComponentProps;
25
  /** Helper methods available in the component (optional) */
26
  methods?: ComponentMethods;
27
  /** Lifecycle hooks for component activation/deactivation (optional) */
28
  hooks?: ComponentHooks;
29
  /** Event deduplication strategy (optional) */
30
  dedupe?: DedupeStrategy;
31
  /** Main execution method called when component is triggered (required) */
32
  run: (event: any) => Promise<void> | void;
33
}
34
```
35

36
**Usage Example:**
37

38
```typescript
39
import { PipedreamComponent } from "@pipedream/types";
40

41
const myComponent: PipedreamComponent = {
42
  key: "my-custom-component",
43
  name: "My Custom Component",
44
  version: "1.0.0",
45
  description: "A custom component that processes data",
46
  props: {
47
    timer: {
48
      type: "$.interface.timer",
49
      default: { intervalSeconds: 300 }
50
    },
51
    message: {
52
      type: "string",
53
      label: "Message",
54
      description: "Message to process"
55
    }
56
  },
57
  async run(event) {
58
    console.log("Processing:", this.message);
59
    this.$emit({ processed: true });
60
  }
61
};
62
```
63

64
### PipedreamApp Interface
65

66
Interface for defining app integrations that provide authentication and shared functionality.
67

68
```typescript { .api }
69
/**
70
 * Interface for defining app integrations with authentication and shared methods
71
 */
72
interface PipedreamApp {
73
  /** Always "app" for app definitions */
74
  type: "app";
75
  /** App identifier slug */
76
  app: string;
77
  /** Reusable property definitions for components using this app */
78
  propDefinitions?: PropDefinitions;
79
  /** App-specific helper methods */
80
  methods?: AppMethods;
81
}
82
```
83

84
**Usage Example:**
85

86
```typescript
87
import { PipedreamApp } from "@pipedream/types";
88

89
const myApp: PipedreamApp = {
90
  type: "app",
91
  app: "my_service",
92
  propDefinitions: {
93
    userId: {
94
      type: "string",
95
      label: "User ID",
96
      description: "The ID of the user to process"
97
    }
98
  },
99
  methods: {
100
    async getUser(id: string) {
101
      // App-specific method implementation
102
      return await this.makeRequest(`/users/${id}`);
103
    }
104
  }
105
};
106
```
107

108
### Component Methods
109

110
Type definition for component helper methods.
111

112
```typescript { .api }
113
/**
114
 * Interface for component helper methods
115
 */
116
interface ComponentMethods {
117
  [methodName: string]: (...args: any[]) => any;
118
}
119
```
120

121
### App Methods
122

123
Type definition for app-specific methods.
124

125
```typescript { .api }
126
/**
127
 * Interface for app-specific methods available to components using the app
128
 */
129
interface AppMethods {
130
  [methodName: string]: (...args: any[]) => any;
131
}
132
```
133

134
### Component Hooks
135

136
Lifecycle hooks for component activation and deactivation.
137

138
```typescript { .api }
139
/**
140
 * Lifecycle hooks for component activation and deactivation
141
 */
142
interface ComponentHooks {
143
  /** Called when component is activated (optional) */
144
  activate?: () => Promise<void> | void;
145
  /** Called when component is deactivated (optional) */
146
  deactivate?: () => Promise<void> | void;
147
}
148
```
149

150
**Usage Example:**
151

152
```typescript
153
const componentWithHooks: PipedreamComponent = {
154
  name: "Component with Hooks",
155
  version: "1.0.0",
156
  props: { /* props */ },
157
  hooks: {
158
    async activate() {
159
      console.log("Component activated");
160
      // Setup resources, create webhooks, etc.
161
    },
162
    async deactivate() {
163
      console.log("Component deactivated");
164
      // Cleanup resources, remove webhooks, etc.
165
    }
166
  },
167
  async run(event) {
168
    // Component logic
169
  }
170
};
171
```
172

173
### Deduplication Strategies
174

175
Enum for event deduplication strategies.
176

177
```typescript { .api }
178
/**
179
 * Event deduplication strategy options
180
 */
181
type DedupeStrategy = 
182
  | "unique"    // Dedupe by event ID
183
  | "greatest"  // Keep event with greatest ID
184
  | "last";     // Keep most recent event
185
```
186

187
**Usage Example:**
188

189
```typescript
190
const componentWithDedupe: PipedreamComponent = {
191
  name: "Deduped Component",
192
  version: "1.0.0",
193
  dedupe: "unique", // Events will be deduped by their ID
194
  props: { /* props */ },
195
  async run(event) {
196
    // Emit event with ID for deduplication
197
    this.$emit(event, { id: event.id });
198
  }
199
};
200
```
201

202
### Prop Definitions
203

204
Interface for reusable property definitions in apps.
205

206
```typescript { .api }
207
/**
208
 * Reusable property definitions for apps
209
 */
210
interface PropDefinitions {
211
  [propName: string]: UserInputProp;
212
}
213
```
214

215
### Component Props Structure
216

217
Container type for all component properties.
218

219
```typescript { .api }
220
/**
221
 * Container for all component properties including user inputs, interfaces, and services
222
 */
223
interface ComponentProps {
224
  [propName: string]: 
225
    | UserInputProp
226
    | TimerInterface
227
    | HttpInterface
228
    | AppHookInterface
229
    | "$.service.db"
230
    | PipedreamApp;
231
}
232
```
233

234
## Common Patterns
235

236
### Timer-Based Component
237

238
```typescript
239
import { PipedreamComponent, TimerInterface } from "@pipedream/types";
240

241
const timerComponent: PipedreamComponent = {
242
  name: "Timer Component",
243
  version: "1.0.0",
244
  props: {
245
    timer: {
246
      type: "$.interface.timer",
247
      default: { intervalSeconds: 60 }
248
    } as TimerInterface,
249
    db: "$.service.db"
250
  },
251
  async run(event) {
252
    // Timer-based logic
253
  }
254
};
255
```
256

257
### HTTP Endpoint Component
258

259
```typescript
260
import { PipedreamComponent, HttpInterface } from "@pipedream/types";
261

262
const httpComponent: PipedreamComponent = {
263
  name: "HTTP Component",
264
  version: "1.0.0",
265
  props: {
266
    http: {
267
      type: "$.interface.http",
268
      customResponse: true
269
    } as HttpInterface
270
  },
271
  async run(event) {
272
    this.http.respond({
273
      status: 200,
274
      body: { success: true }
275
    });
276
  }
277
};
278
```
279

280
### App Integration Component
281

282
```typescript
283
import { PipedreamComponent, PipedreamApp } from "@pipedream/types";
284

285
const appComponent: PipedreamComponent = {
286
  name: "App Integration Component",
287
  version: "1.0.0",
288
  props: {
289
    myApp: {
290
      type: "app",
291
      app: "my_service"
292
    } as PipedreamApp,
293
    userId: {
294
      type: "string",
295
      propDefinition: ["myApp", "userId"]
296
    }
297
  },
298
  async run(event) {
299
    const user = await this.myApp.getUser(this.userId);
300
    this.$emit(user);
301
  }
302
};
303
```