0
# Promise Service
1

2
Vue context-aware Promise wrapper that automatically binds callback functions to the appropriate Vue component context, ensuring proper `this` binding in async operations.
3

4
## Capabilities
5

6
### Promise Creation
7

8
Create context-aware promises that maintain proper Vue component binding.
9

10
```javascript { .api }
11
/**
12
 * Create a Vue context-aware promise
13
 * @param executor - Promise executor function or existing Promise
14
 * @returns PromiseObj with Vue context binding
15
 */
16
function $promise(executor: (resolve: Function, reject: Function) => void): PromiseObj;
17

18
/**
19
 * Static Promise constructor (on Vue.Promise)
20
 * @param executor - Promise executor function or existing Promise  
21
 * @param context - Vue component context for binding
22
 * @returns PromiseObj with specified context binding
23
 */
24
function Promise(executor: Function | Promise, context?: any): PromiseObj;
25
```
26

27
**Usage Examples:**
28

29
```javascript
30
// Instance method (automatically binds to component context)
31
export default {
32
  methods: {
33
    async fetchUserData() {
34
      return this.$promise((resolve, reject) => {
35
        setTimeout(() => {
36
          resolve({ name: 'John', id: 1 });
37
        }, 1000);
38
      }).then(function(userData) {
39
        // 'this' is automatically bound to the Vue component
40
        this.user = userData;
41
        console.log('User loaded:', this.user.name);
42
      });
43
    }
44
  }
45
}
46

47
// Static method with explicit context
48
const promise = Vue.Promise((resolve, reject) => {
49
  resolve('Hello');
50
}, this);
51
```
52

53
### Static Promise Methods
54

55
Utility methods for creating promises from iterables and values.
56

57
```javascript { .api }
58
/**
59
 * Create a promise that resolves when all promises in iterable resolve
60
 * @param iterable - Array of promises or values
61
 * @param context - Vue component context for binding
62
 * @returns PromiseObj that resolves with array of results
63
 */
64
function Promise.all(iterable: any[], context?: any): PromiseObj;
65

66
/**
67
 * Create a promise that resolves with the given value
68
 * @param value - Value to resolve with
69
 * @param context - Vue component context for binding  
70
 * @returns PromiseObj that resolves with value
71
 */
72
function Promise.resolve(value: any, context?: any): PromiseObj;
73

74
/**
75
 * Create a promise that rejects with the given reason
76
 * @param reason - Reason for rejection
77
 * @param context - Vue component context for binding
78
 * @returns PromiseObj that rejects with reason
79
 */
80
function Promise.reject(reason: any, context?: any): PromiseObj;
81

82
/**
83
 * Create a promise that resolves/rejects with the first settled promise
84
 * @param iterable - Array of promises or values
85
 * @param context - Vue component context for binding
86
 * @returns PromiseObj that settles with first result
87
 */
88
function Promise.race(iterable: any[], context?: any): PromiseObj;
89
```
90

91
**Usage Examples:**
92

93
```javascript
94
// Promise.all with context binding
95
Vue.Promise.all([
96
  this.$http.get('/api/users'),
97
  this.$http.get('/api/posts'),
98
  this.$http.get('/api/comments')
99
], this).then(function([users, posts, comments]) {
100
  // 'this' refers to the Vue component
101
  this.users = users.body;
102
  this.posts = posts.body;
103
  this.comments = comments.body;
104
});
105

106
// Promise.resolve with immediate value
107
Vue.Promise.resolve({ message: 'Success' }, this)
108
  .then(function(result) {
109
    this.status = result.message;
110
  });
111

112
// Promise.race for timeout functionality
113
Vue.Promise.race([
114
  this.$http.get('/api/slow-endpoint'),
115
  Vue.Promise.reject('Timeout after 5s', this)
116
], this).catch(function(error) {
117
  this.error = error;
118
});
119
```
120

121
### Promise Instance Methods
122

123
Methods available on PromiseObj instances for chaining and context management.
124

125
```javascript { .api }
126
/**
127
 * Set or change the context binding for this promise
128
 * @param context - Vue component or object to bind callbacks to
129
 * @returns Same PromiseObj instance for chaining
130
 */
131
bind(context: any): PromiseObj;
132

133
/**
134
 * Add fulfillment and rejection handlers with automatic context binding
135
 * @param fulfilled - Success callback (will be bound to context)
136
 * @param rejected - Error callback (will be bound to context)
137
 * @returns New PromiseObj for chaining
138
 */
139
then(fulfilled?: (value: any) => any, rejected?: (reason: any) => any): PromiseObj;
140

141
/**
142
 * Add rejection handler with automatic context binding
143
 * @param rejected - Error callback (will be bound to context)
144
 * @returns New PromiseObj for chaining
145
 */
146
catch(rejected: (reason: any) => any): PromiseObj;
147

148
/**
149
 * Add a callback that runs regardless of promise outcome
150
 * @param callback - Callback to run after promise settles
151
 * @returns New PromiseObj for chaining
152
 */
153
finally(callback: () => void): PromiseObj;
154
```
155

156
**Usage Examples:**
157

158
```javascript
159
// Context rebinding
160
const promise = Vue.Promise.resolve('Hello');
161
promise.bind(this).then(function(value) {
162
  // 'this' now refers to the bound context
163
  this.message = value;
164
});
165

166
// Chaining with automatic context binding
167
this.$promise((resolve) => {
168
  setTimeout(() => resolve('Delayed result'), 1000);
169
})
170
.then(function(result) {
171
  this.result = result;
172
  return this.$http.post('/api/log', {message: result});
173
})
174
.then(function(response) {
175
  this.logged = true;
176
})
177
.catch(function(error) {
178
  this.error = error.message;
179
})
180
.finally(function() {
181
  this.loading = false;
182
});
183
```
184

185
### Context Binding Behavior
186

187
The Promise service automatically binds callback functions to the appropriate Vue component context.
188

189
**Usage Examples:**
190

191
```javascript
192
export default {
193
  data() {
194
    return {
195
      users: [],
196
      loading: false,
197
      error: null
198
    };
199
  },
200
  
201
  methods: {
202
    loadUsers() {
203
      this.loading = true;
204
      
205
      // Without Vue.Promise - 'this' binding is lost
206
      new Promise((resolve) => {
207
        setTimeout(() => resolve(['John', 'Jane']), 1000);
208
      }).then(function(users) {
209
        // 'this' is undefined or wrong context!
210
        this.users = users; // Error!
211
      });
212
      
213
      // With Vue.Promise - 'this' is automatically bound
214
      this.$promise((resolve) => {
215
        setTimeout(() => resolve(['John', 'Jane']), 1000);
216
      }).then(function(users) {
217
        // 'this' correctly refers to the Vue component
218
        this.users = users;
219
        this.loading = false;
220
      }).catch(function(error) {
221
        this.error = error;
222
        this.loading = false;
223
      });
224
    }
225
  }
226
}
227
```
228

229
## Types
230

231
```javascript { .api }
232
interface PromiseObj {
233
  /** Underlying native Promise instance */
234
  promise: Promise<any>;
235
  /** Vue component context for callback binding */
236
  context: any;
237
  
238
  /** Bind callbacks to specified context */
239
  bind(context: any): PromiseObj;
240
  /** Add success/error handlers with context binding */
241
  then(fulfilled?: Function, rejected?: Function): PromiseObj;
242
  /** Add error handler with context binding */
243
  catch(rejected: Function): PromiseObj;
244
  /** Add cleanup handler that runs regardless of outcome */
245
  finally(callback: Function): PromiseObj;
246
}
247

248
interface PromiseConstructor {
249
  /** Create context-aware promise from all promises in iterable */
250
  all(iterable: any[], context?: any): PromiseObj;
251
  /** Create context-aware promise that resolves with value */
252
  resolve(value: any, context?: any): PromiseObj;
253
  /** Create context-aware promise that rejects with reason */
254
  reject(reason: any, context?: any): PromiseObj;
255
  /** Create context-aware promise that races promises in iterable */
256
  race(iterable: any[], context?: any): PromiseObj;
257
}
258
```