|
| 1 | +# {Promise} is used to help structure asynchronous code. |
| 2 | +# |
| 3 | +# It is available in the Opal standard library, and can be required in any Opal |
| 4 | +# application: |
| 5 | +# |
| 6 | +# require 'promise' |
| 7 | +# |
| 8 | +# ## Basic Usage |
| 9 | +# |
| 10 | +# Promises are created and returned as objects with the assumption that they |
| 11 | +# will eventually be resolved or rejected, but never both. A {Promise} has |
| 12 | +# a {#then} and {#fail} method (or one of their aliases) that can be used to |
| 13 | +# register a block that gets called once resolved or rejected. |
| 14 | +# |
| 15 | +# promise = Promise.new |
| 16 | +# |
| 17 | +# promise.then { |
| 18 | +# puts "resolved!" |
| 19 | +# }.fail { |
| 20 | +# puts "rejected!" |
| 21 | +# } |
| 22 | +# |
| 23 | +# # some time later |
| 24 | +# promise.resolve |
| 25 | +# |
| 26 | +# # => "resolved!" |
| 27 | +# |
| 28 | +# It is important to remember that a promise can only be resolved or rejected |
| 29 | +# once, so the block will only ever be called once (or not at all). |
| 30 | +# |
| 31 | +# ## Resolving Promises |
| 32 | +# |
| 33 | +# To resolve a promise, means to inform the {Promise} that it has succeeded |
| 34 | +# or evaluated to a useful value. {#resolve} can be passed a value which is |
| 35 | +# then passed into the block handler: |
| 36 | +# |
| 37 | +# def get_json |
| 38 | +# promise = Promise.new |
| 39 | +# |
| 40 | +# HTTP.get("some_url") do |req| |
| 41 | +# promise.resolve req.json |
| 42 | +# end |
| 43 | +# |
| 44 | +# promise |
| 45 | +# end |
| 46 | +# |
| 47 | +# get_json.then do |json| |
| 48 | +# puts "got some JSON from server" |
| 49 | +# end |
| 50 | +# |
| 51 | +# ## Rejecting Promises |
| 52 | +# |
| 53 | +# Promises are also designed to handle error cases, or situations where an |
| 54 | +# outcome is not as expected. Taking the previous example, we can also pass |
| 55 | +# a value to a {#reject} call, which passes that object to the registered |
| 56 | +# {#fail} handler: |
| 57 | +# |
| 58 | +# def get_json |
| 59 | +# promise = Promise.new |
| 60 | +# |
| 61 | +# HTTP.get("some_url") do |req| |
| 62 | +# if req.ok? |
| 63 | +# promise.resolve req.json |
| 64 | +# else |
| 65 | +# promise.reject req |
| 66 | +# end |
| 67 | +# |
| 68 | +# promise |
| 69 | +# end |
| 70 | +# |
| 71 | +# get_json.then { |
| 72 | +# # ... |
| 73 | +# }.fail { |req| |
| 74 | +# puts "it went wrong: #{req.message}" |
| 75 | +# } |
| 76 | +# |
| 77 | +# ## Chaining Promises |
| 78 | +# |
| 79 | +# Promises become even more useful when chained together. Each {#then} or |
| 80 | +# {#fail} call returns a new {Promise} which can be used to chain more and more |
| 81 | +# handlers together. |
| 82 | +# |
| 83 | +# promise.then { wait_for_something }.then { do_something_else } |
| 84 | +# |
| 85 | +# Rejections are propagated through the entire chain, so a "catch all" handler |
| 86 | +# can be attached at the end of the tail: |
| 87 | +# |
| 88 | +# promise.then { ... }.then { ... }.fail { ... } |
| 89 | +# |
| 90 | +# ## Composing Promises |
| 91 | +# |
| 92 | +# {Promise.when} can be used to wait for more than one promise to resolve (or |
| 93 | +# reject). Using the previous example, we could request two different json |
| 94 | +# requests and wait for both to finish: |
| 95 | +# |
| 96 | +# Promise.when(get_json, get_json2).then |first, second| |
| 97 | +# puts "got two json payloads: #{first}, #{second}" |
| 98 | +# end |
| 99 | +# |
1 | 100 | class Promise |
2 | 101 | def self.value(value) |
3 | 102 | new.resolve(value) |
|
0 commit comments