{"id":15069120,"url":"https://github.com/sparky983/java-promises","last_synced_at":"2025-10-05T06:31:15.052Z","repository":{"id":40579036,"uuid":"440378378","full_name":"Sparky983/java-promises","owner":"Sparky983","description":"A promise library for Java with similar syntax to JavaScript","archived":true,"fork":false,"pushed_at":"2023-07-24T21:19:17.000Z","size":336,"stargazers_count":6,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2024-09-30T13:03:11.946Z","etag":null,"topics":["async","java","java-11","java-promises","maven","promise"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Sparky983.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-12-21T03:28:27.000Z","updated_at":"2024-09-18T03:27:34.000Z","dependencies_parsed_at":"2023-02-18T10:05:14.932Z","dependency_job_id":null,"html_url":"https://github.com/Sparky983/java-promises","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sparky983%2Fjava-promises","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sparky983%2Fjava-promises/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sparky983%2Fjava-promises/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sparky983%2Fjava-promises/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sparky983","download_url":"https://codeload.github.com/Sparky983/java-promises/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235370461,"owners_count":18979093,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","java","java-11","java-promises","maven","promise"],"created_at":"2024-09-25T01:40:35.668Z","updated_at":"2025-10-05T06:31:14.686Z","avatar_url":"https://github.com/Sparky983.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"img/banner.png\"\u003e\n\n\u003cp align=\"center\"\u003eJava promise library aimed to have syntax which is very similar to JavaScript. \u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/workflow/status/Sparky983/java-promises/CI?label=Build\u0026style=flat-square\u0026color=ff214e\u0026labelColor=000000\" alt=\"Build Status\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/Sparky983/java-promises?label=License\u0026style=flat-square\u0026color=ff214e\u0026labelColor=000000\" alt=\"License Apache\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/commit-activity/m/Sparky983/java-promises?label=Commits\u0026style=flat-square\u0026color=ff214e\u0026labelColor=000000\" alt=\"Commit activity\"\u003e\n    \u003cimg src=\"https://img.shields.io/static/v1?label=PRs\u0026message=Welcome\u0026style=flat-square\u0026color=ff214e\u0026labelColor=000000\" alt=\"Pull Requests Welcome\"\u003e\n\u003c/p\u003e\n\nNote: although many methods may have the same name as a JavaScript promise method, they may do different \nthings. \n\n## Table of Contents\n\n[1. ](#installation) Installation \\\n[2. ](#what-is-a-promise) What is a promise? \\\n[3. ](#quick-start) Getting Started \\\n[4. ](#built-in-promises) Built in promises\n\n## Installation\n\nThen add the following to your project\n\npom.xml\n```xml\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003esparky-releases\u003c/id\u003e\n        \u003curl\u003ehttps://repo.sparky983.me/releases\u003c/url\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eme.sparky\u003c/groupId\u003e\n        \u003cartifactId\u003ejava-promises\u003c/artifactId\u003e\n        \u003cversion\u003e1.4.0\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\nbuild.gradle\n\n```groovy\nrepositories {\n    maven {\n        url \"https://repo.sparky983.me/releases\"\n    }\n}\n\ndependencies {\n    implementation 'me.sparky:java-promises:1.4.0'\n}\n```\n\nbuild.gradle.kts\n```kotlin\nrepositories {\n    maven {\n        url = uri(\"https://repo.sparky983.me/releases\")\n    }\n}\n\ndependencies {\n    implementation(\"me.sparky:java-promises:1.4.0\")\n}\n```\n\n## What Is A Promise?\n\nA promise is an object that represents an asynchronous operation. We use them avoid blocking \noperations. \n\n## Quick Start\n\n### Install\n\nFollow the [installation](#installation) steps. \n\n### Create and resolve a promise\n\nYou can create a new promise by using constructing a new `CompletablePromise`. \n\nNote that a `Promise` and `CompletablePromise` are different. \n`Promise` is given to the user of your api to for them to use `Promise#then()` and \n`Promise#catchException` to handle the completion of the promise. On the other hand a \n`CompletablePromise` should be used internally for your api to make asynchronous calls. \n\n```java\nPromise\u003cString\u003e promise = new CompletablePromise\u003c\u003e((completablePromise) -\u003e {\n    completablePromise.resolve(\"Resolved!\");\n});\n```\n\nThe first argument is the executor. It is used to resolve or reject the promise asynchronously. You\ncan also do this operation synchronously without an executor by explicitly calling \n`CompletablePromise#resolve(T)` on any `CompletablePromise`\n\n```java\nCompletablePromise\u003cString\u003e promise = new CompletablePromise\u003c\u003e();\npromise.resolve(\"Resolved!\");\n```\n\nTo reject the promise call `CompletablePromise#reject(Throwable)`. You may also optionally throw an\nException inside the executor. \n\n```java\nthrow new Exception(\"Rejected!\");\n\ncompletablePromise.reject(new Exception(\"Rejected!\"));\n```\n\n### Handling promise completion\n\nTo handle a promise's completion you attach a `.then()` or `.catchException()` with a callback as \nthe argument. Unlike JavaScript any exceptions thrown in the `.then()` callback will not be caught\nin `.catchException()`. You either have to handle them yourself or they will be printed to the \nsystem output and swallowed. \n\n```java\npromise\n        .then((value) -\u003e System.out.println(\"Promise resolved with value\" + value))\n        .catchException((reason) -\u003e reason.printStackTrace());\n```\n\nThese callbacks will be called once the promise is completed. `.then()` will be called asynchronously\nif the promise resolves and `.catchException()` if the promise is rejected. They will be called \nimmediately if the promise has already been completed. `.then()` may also optionally be a `Runnable`.\n\n### Advanced\n\nThis section is going to cover more advanced topics such as promise transformation. \n\nTransforming a promise is where you transform the value of a promise into a new one. You can \ntransform promise `Promise#transform(Function\u003cT, R\u003e)` method. Here is an example with fetching\njson data. \n\n```java\npublic static void main(String... args) {\n    get(args[0])\n        .then((data) -\u003e System.out.println(\"Recieved json data \\n\" + json));\n}\n\npublic Promise\u003cJSON\u003e get(@NotNull String url) {\n    return get(url).transform(JSON::parse);\n}\n```\n\n## Built-in Promises\n\nThere are a few built in promise classes. You can access them via a static method in the\n`me.sparky.promises.Promise` class. \n\n### All Built-in Promises\n\n[Promise.resolve(result)](#resolved-promise) \\\n[Promise.reject(reason)](#rejected-promise) \\\n[Promise.all(promises)](#all-promise) \\\n[Promise.any(promises)](#any-promise) \\\n[Promise.whenAll(promises)](#when-all-promise) \\\n[Promise.allSettled(promises)](#all-settled-promise)\n\n#### Resolved Promise\n\n```java\nPromise.resolve(@Nullable T);\n```\nDescription: Returns a resolved promise. \n\n#### Rejected Promise\n\n```java\nPromise.reject(@NotNull Throwable);\n```\nDescription: Returns a rejected promise. \n\n#### All Promise\n```java\nPromise.all(@NotNull Promise\u003cT\u003e...);\n```\nDescription: Returns a promise that is resolved when all input promises are resolved. \n\n#### Any Promise\n```java\nPromise.any(@NotNull Promise\u003cT\u003e...);\n```\nDescription: Returns a promise that is resolved when any input promises are resolved. \n\n#### When All Promise\n```java\nPromise.whenAll(@NotNull Promise\u003c?\u003e...);\n```\nDescription: Returns a promise that resolves when all input promises are resolved. \n\n#### All Settled Promise\n```java\nPromise.allSettled(@NotNull Promise\u003c?\u003e...);\n```\nDescription: Returns a promise that resolves when all the inputs are settled (completed).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparky983%2Fjava-promises","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsparky983%2Fjava-promises","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparky983%2Fjava-promises/lists"}