0
# @pipedream/types
1

2
@pipedream/types provides comprehensive TypeScript type definitions for Pipedream's component development ecosystem. It enables developers to build type-safe Pipedream components including event sources and actions by providing interfaces, type definitions, and schemas that cover the complete component API structure.
3

4
## Package Information
5

6
- **Package Name**: @pipedream/types
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @pipedream/types`
10

11
## Core Imports
12

13
```typescript
14
import { PipedreamComponent, ComponentProps, TimerInterface, HttpInterface } from "@pipedream/types";
15
```
16

17
For importing specific type categories:
18

19
```typescript
20
import { 
21
  // Component structure
22
  PipedreamComponent, PipedreamApp,
23
  
24
  // Props and interfaces
25
  UserInputProp, ComponentProps, TimerInterface, HttpInterface,
26
  
27
  // Events and context
28
  ComponentThis, EmitMethod, EventMetadata,
29
  
30
  // Utilities
31
  DedupeStrategy, AuthContext
32
} from "@pipedream/types";
33
```
34

35
## Basic Usage
36

37
```typescript
38
import { PipedreamComponent, ComponentProps, TimerInterface } from "@pipedream/types";
39

40
// Define a basic timer-based component
41
const component: PipedreamComponent = {
42
  key: "example-timer-component",
43
  name: "Example Timer Component",
44
  version: "0.0.1",
45
  description: "An example component that runs on a timer",
46
  props: {
47
    timer: {
48
      type: "$.interface.timer",
49
      default: {
50
        intervalSeconds: 60 * 15, // 15 minutes
51
      },
52
    },
53
    db: "$.service.db",
54
  },
55
  async run(event) {
56
    // Access typed context
57
    const { timer, db, $emit } = this;
58
    
59
    // Emit typed events
60
    this.$emit({ message: "Timer triggered" }, {
61
      id: Date.now(),
62
      summary: "Timer execution",
63
      ts: Date.now(),
64
    });
65
  },
66
};
67
```
68

69
## Architecture
70

71
@pipedream/types is organized around several key type systems:
72

73
- **Component Structure**: Core interfaces for defining Pipedream components (`PipedreamComponent`, `PipedreamApp`)
74
- **Prop System**: Complete typing for component properties including user inputs, interfaces, and services
75
- **Interface Types**: Strongly typed interfaces for triggers (`TimerInterface`, `HttpInterface`, `AppHookInterface`)
76
- **Context Types**: Runtime context objects available during component execution (`ComponentThis`, `AuthContext`)
77
- **Event System**: Types for event emission and metadata (`EmitMethod`, `EventMetadata`)
78
- **Validation Types**: Schema definitions and validation patterns for component configuration
79

80
## Capabilities
81

82
### Component Structure
83

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

86
```typescript { .api }
87
interface PipedreamComponent {
88
  key?: string;
89
  name: string;
90
  version: string;
91
  description?: string;
92
  props: ComponentProps;
93
  methods?: ComponentMethods;
94
  hooks?: ComponentHooks;
95
  dedupe?: DedupeStrategy;
96
  run: (event: any) => Promise<void> | void;
97
}
98

99
interface PipedreamApp {
100
  type: "app";
101
  app: string;
102
  propDefinitions?: PropDefinitions;
103
  methods?: AppMethods;
104
}
105
```
106

107
[Component Structure](./component-structure.md)
108

109
### Prop Types
110

111
Comprehensive type system for component properties including user input props, validation schemas, and dynamic option loading.
112

113
```typescript { .api }
114
interface UserInputProp {
115
  type: PropType;
116
  label?: string;
117
  description?: string;
118
  optional?: boolean;
119
  default?: any;
120
  secret?: boolean;
121
  options?: PropOptions;
122
  useQuery?: boolean;
123
  propDefinition?: [PipedreamApp, string, any?];
124
  appProp?: string;
125
  baseIdProp?: string;
126
  tableIdProp?: string;
127
}
128

129
type PropType = 
130
  | "string" | "boolean" | "integer" | "app"
131
  | "string[]" | "boolean[]" | "integer[]"
132
  | "$.airtable.baseId" | "$.airtable.tableId" | "$.airtable.viewId";
133
```
134

135
[Prop Types](./prop-types.md)
136

137
### Interface Types
138

139
Strongly typed interfaces for component triggers including timer-based execution, HTTP endpoints, and app webhooks.
140

141
```typescript { .api }
142
interface TimerInterface {
143
  type: "$.interface.timer";
144
  default?: {
145
    intervalSeconds?: number;
146
    cron?: string;
147
  };
148
}
149

150
interface HttpInterface {
151
  type: "$.interface.http";
152
  customResponse?: boolean;
153
  respond?: HttpRespondMethod;
154
}
155

156
interface AppHookInterface {
157
  type: "$.interface.apphook";
158
  appProp: string;
159
  eventNames: string[];
160
}
161
```
162

163
[Interface Types](./interface-types.md)
164

165
### Event System
166

167
Types for event emission, metadata, and deduplication strategies used throughout the Pipedream component lifecycle.
168

169
```typescript { .api }
170
interface EmitMethod {
171
  (event: any, metadata?: EventMetadata): void;
172
}
173

174
interface EventMetadata {
175
  id?: string | number;
176
  summary?: string;
177
  ts?: number;
178
}
179

180
type DedupeStrategy = "unique" | "greatest" | "last";
181
```
182

183
[Event System](./event-system.md)
184

185
### Component Context
186

187
Runtime context types available during component execution, including access to props, services, and authentication.
188

189
```typescript { .api }
190
interface ComponentThis {
191
  [propName: string]: any;
192
  $emit: EmitMethod;
193
  $auth?: AuthContext;
194
  db?: DatabaseService;
195
  http?: HttpEndpoint & { respond: HttpRespondMethod };
196
}
197

198
interface AuthContext {
199
  oauth_access_token?: string;
200
  oauth_refresh_token?: string;
201
  api_key?: string;
202
  [key: string]: any;
203
}
204
```
205

206
[Component Context](./component-context.md)
207

208
### Service Types
209

210
Type definitions for Pipedream's built-in services including database storage and HTTP response handling.
211

212
```typescript { .api }
213
interface DatabaseService {
214
  type: "$.service.db";
215
  get: (key: string) => any;
216
  set: (key: string, value: any) => void;
217
}
218

219
interface HttpRespondMethod {
220
  (response: {
221
    status: number;
222
    headers?: Record<string, string>;
223
    body?: string | object | Buffer;
224
  }): void;
225
}
226
```
227

228
[Service Types](./service-types.md)