https://github.com/polymeris/cljs-aws
Unofficial AWS client for Clojurescript on Node.js or in the browser
https://github.com/polymeris/cljs-aws
aws aws-sdk clojurescript
Last synced: 8 months ago
JSON representation
Unofficial AWS client for Clojurescript on Node.js or in the browser
- Host: GitHub
- URL: https://github.com/polymeris/cljs-aws
- Owner: polymeris
- License: epl-1.0
- Created: 2018-10-07T18:51:28.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2018-10-26T00:35:53.000Z (over 7 years ago)
- Last Synced: 2025-10-22T01:42:24.039Z (8 months ago)
- Topics: aws, aws-sdk, clojurescript
- Language: Clojure
- Homepage:
- Size: 71.3 KB
- Stars: 24
- Watchers: 1
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# cljs-aws
Unofficial AWS client for Clojurescript using core.async on Node or in the browser.
Tested and working, but still to be considered in **alpha** stage, any interfaces might change.
[](https://clojars.org/cljs-aws)
[](https://circleci.com/gh/polymeris/cljs-aws)
## Usage
[:book: API Reference at cljdoc](https://cljdoc.org/d/cljs-aws/cljs-aws/CURRENT/api/cljs-aws)|
-----------------------------------------------------------------------------------|
```clojure
(ns example
(:require [cljs.core.async :refer [go {:location "http://examplebucket.s3.amazonaws.com/"}
; or
;=> {:error "msg"}
```
### Authentication
For node, use the underlying
[node authentication mechanism](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-node.html),
in practice most likely setting your credentials using environment variables like `AWS_PROFILE` or `AWS_ACCESS_KEY_ID`
and `AWS_SECRET_ACCESS_KEY`.
For the browser, use a Cognito identity pool, and load the credentials as follows:
```clojure
(aws-cljs.base.config/load-credentials! :cognito-identity-credentials {:identity-pool-id ""})
```
### Examples
The [`node-examples`](node-examples/src/cljs_aws) and [`browser-examples`](browser-examples/src/cljs_aws) directories contains a few examples on how to use different AWS services.
#### Node
To run Node examples, first set your AWS credentials, e.g.:
```
export AWS_PROFILE=myprofile
export AWS_REGION=us-east-1
```
Then, build and run:
```
cd node-examples
lein cljsbuild once dynamodb # or another example
node target/dynamodb.js
```
#### Browser
To run browser examples, follow [the first step in this tutorial](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/getting-started-browser.html)
to create a Cognito Identity Pool, then give the IAM role associated with unauthenticated users permissions to access the
service you are testing.
Edit the example code to use your Cognito Identity Pool ID, and run figwheel:
```
cd browser-examples
lein figwheel lambda
```
### A note on naming, parameters and return values
The names of the functions in each namespace are generated automatically from the PascalCase'd operation names,
so for instance DynamoDB's [`PutItem`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB.html#putItem-property)
operation becomes `dynamodb/put-item`.
Parameters and return values are also converted between camel-case and PascalCase for you, so for instance, in
`(dynamodb/describe-table {:table-name "mytable"})`, the parameter will become `{"TableName": "mytable"}`.
However, there are cases were that's not desirable. In particular, when using DynamoDB, the schema might contain
all lower-case or all upper-case named columns, and some types are also indicated by all upper-case strings, like
`BS`, `NS`, `SS`.
cljs-aws doesn't try to be clever about those special cases (let's leave that for a higher level library), but instead
allows you to pass string keys, which (unlike keywords) will not be re-cased or transformed in any way:
```clojure
(dyanmodb/put-item {:table-name "mytable"
:item {"id" {"S" "foo"} ; "id" *not* re-cased to "Id"
:numbers-set {"NS" #{}}}}) ; :numbers-set *is* PascalCased'd, but "NS" is not
```
## Development
Install the AWS SDK via npm:
```
lein npm install
```
The tests are ran with doo:
```
lein doo node test-node auto # or "once"
lein doo phantom test-browser auto
```
If you have modified the root library and try to run the examples you will get an error similar to
`Could not find artifact cljs-aws:cljs-aws:jar:x.y.z-DIRTY in central`, since the modified version does not exist
in the maven repositories. Install a local copy of the library by running:
```
lein download-deps
lein install
```
Deployment to clojars is handled by the CI/CD pipeline, and, if the tests pass, will run for any git tag starting with
`v`.