mirror of
https://github.com/digital-asset/daml.git
synced 2024-09-11 12:59:17 +03:00
docs: better readme's for ts libraries (#4954)
CHANGELOG_BEGIN CHANGELOG_END
This commit is contained in:
Robin Krom
GitHub
parent
19f5b86c79
commit
254ee50b7c
@ -1,25 +1,75 @@
|
||||
# @daml/ledger
|
||||
|
||||
> Client side API implementation for a DAML based ledger. This library implements the JSON based API for a DAML ledger documented in the [DAML Docs](https://docs.daml.com/json-api/index.html).
|
||||
> Client side API implementation for a DAML based ledgers. This library implements the [JSON
|
||||
> API](https://docs.daml.com/json-api/index.html) for a DAML ledger.
|
||||
|
||||
## Install
|
||||
## Documentation
|
||||
|
||||
### npm:
|
||||
|
||||
```sh
|
||||
npm install @daml/ledger
|
||||
```
|
||||
|
||||
### yarn:
|
||||
|
||||
```sh
|
||||
yarn add @daml/ledger
|
||||
```
|
||||
Comprehensive documentation for `@daml/ledger` can be found
|
||||
[here](https://docs.daml.com/app-dev/bindings-ts/daml-ledger/index.html).
|
||||
|
||||
## Usage
|
||||
|
||||
The best place to get you started is [Create DAML App](https://github.com/digital-asset/create-daml-app)
|
||||
and the [Quickstart Guide](https://docs.daml.com/getting-started/quickstart.html).
|
||||
The best way to get you started quickly is to look at [Create DAML
|
||||
App](https://github.com/digital-asset/create-daml-app) and to read the the [Quickstart
|
||||
Guide](https://docs.daml.com/getting-started/quickstart.html).
|
||||
|
||||
We recommend to use the [React](https://reactjs.org) framework and the `@daml/react` library to
|
||||
build frontends for DAML applications. If you choose a different Javascript based framework, please
|
||||
take a look at the source of `@daml/react` and it's usage of the `@daml/ledger` library.
|
||||
|
||||
The main export of `@daml/ledger` is the `Ledger` class. It's constructor takes an authentication
|
||||
token used to communicate with the [JSON API](https://docs.daml.com/json-api/index.html), an HTTP
|
||||
base URL and a websocket base URL.
|
||||
|
||||
An instance of the `Ledger` class provides the following methods to communicate with a DAML ledger.
|
||||
Please consult the [documentation](https://docs.daml.com/app-dev/bindings-ts/daml-ledger/index.html)
|
||||
for their exact signatures.
|
||||
|
||||
`create`
|
||||
--------
|
||||
Create a new contract of the given template with given arguments.
|
||||
|
||||
`archive`
|
||||
---------
|
||||
Archive a contract identified by its contract id.
|
||||
|
||||
`archiveByKey`
|
||||
--------------
|
||||
Archive a contract identified by its contract key.
|
||||
|
||||
`exercise`
|
||||
----------
|
||||
Exercise a choice on a contract identified by its contract id.
|
||||
|
||||
`exerciseByKey`
|
||||
---------------
|
||||
Exercise a choice on a contract identified by its contract key.
|
||||
|
||||
`query`
|
||||
-------
|
||||
Retrieve contracts for a given template matching a given query. If no query is given, all contracts
|
||||
of that template visible for the submitting party are returned.
|
||||
|
||||
`streamQuery`
|
||||
-------------
|
||||
Retrieve a consolidated stream of events for a given template and query. The accumulated state is
|
||||
the current set of active contracts matching the query. An event can be a `CreateEvent` or an
|
||||
`ArchiveEvent`. When no `query` argument is given, all events visible to the submitting party are
|
||||
returned.
|
||||
|
||||
`fetch`
|
||||
-------
|
||||
Fetch a contract identified by its contract id.
|
||||
|
||||
`fetchByKey`
|
||||
------------
|
||||
Fetch a contract identified by its contract key.
|
||||
|
||||
`streamFetchByKey`
|
||||
------------------
|
||||
Retrieve a consolidated stream of `CreateEvent`'s for a given template and contract key.
|
||||
|
||||
|
||||
## Source
|
||||
https://github.com/digital-asset/daml/tree/master/language-support/ts/daml-ledger
|
||||
|
||||
@ -1,52 +1,115 @@
|
||||
# @daml/react
|
||||
|
||||
> Library to interact with a DAML ledger from a React application.
|
||||
> React framework for DAML applications
|
||||
|
||||
## Install
|
||||
## Documentation
|
||||
|
||||
### npm:
|
||||
|
||||
```sh
|
||||
npm install @daml/react
|
||||
```
|
||||
|
||||
### yarn:
|
||||
|
||||
```sh
|
||||
yarn add @daml/react
|
||||
```
|
||||
Comprehensive documentation for `@daml/react` can be found [here](https://docs.daml.com/app-dev/bindings-ts/daml-react/index.html).
|
||||
|
||||
## Usage
|
||||
|
||||
The best place to get you started is [Create DAML App](https://github.com/digital-asset/create-daml-app)
|
||||
and the [Quickstart Guide](https://docs.daml.com/getting-started/quickstart.html).
|
||||
The best way to get you started quickly is to look at [Create DAMLApp](https://github.com/digital-asset/create-daml-app)
|
||||
and to read the [QuickstartGuide](https://docs.daml.com/getting-started/quickstart.html).
|
||||
|
||||
Here is a Typescript/React example:
|
||||
To get an overview on how to build a DAML application, please read the [application architecture overview](https://docs.daml.com/app-dev/index.html).
|
||||
|
||||
To use `@daml/react` your application needs to be connected to the JSON API of a DAML ledger. If
|
||||
your JSON API server for the ledger runs on the local host on port 7575, set
|
||||
|
||||
``` json
|
||||
"proxy": "http://localhost:7575"
|
||||
```
|
||||
|
||||
in your `package.json` and wrap your main component in the `DamlLedger` component of `@daml/react`
|
||||
|
||||
```typescript
|
||||
import {useParty, ...} from @daml/react
|
||||
```
|
||||
import DamlLeddger from @daml/react
|
||||
|
||||
React entry point:
|
||||
|
||||
```typescript
|
||||
const App: React.FC = () => {
|
||||
const [credentials, setCredentials] = useState<Credentials | undefined>();
|
||||
|
||||
return credentials
|
||||
? <DamlLedger credentials={credentials}>
|
||||
<MainScreen onLogout={() => setCredentials(undefined)}/>
|
||||
</DamlLedger>
|
||||
: <LoginScreen onLogin={setCredentials}/>;
|
||||
<DamlLedger
|
||||
token: <your authentication token>
|
||||
httpBaseUrl?: <optional http base url>
|
||||
wsBaseUrl?: <optional websocket base url>
|
||||
party: <the logged in party>
|
||||
>
|
||||
<MainScreen />
|
||||
</DamlLedger>
|
||||
}
|
||||
```
|
||||
DAML Ledger API | Code
|
||||
----------------|-----
|
||||
Get the logged in party | `const party = useParty();` <br> `...` <br> `<h1> You're logged in as {party} </h1>`
|
||||
Exercise a choice on a contract | `const [exerciseChoice] = useExercise(ContractTemplate.ChoiceName)` <br> `...` <br> `onClick={() => exerciseChoice(contractId, arguments)}`
|
||||
Query the ledger | `const {loading: isLoading, contracts: queryResult} = useQuery(ContractTemplate, () => ({field: value}), [dependency1, dependency2, ... ]) `
|
||||
Query for contract keys | `const contracts = useFetchByKey(ContractTemplate, () => key, [dependency1, dependency2, ...])`
|
||||
Reload the query results | `reload = useReload();` <br> `...` <br> `onClick={() => reload()}`
|
||||
|
||||
Now you can use the following React hooks to interact with a DAML ledger:
|
||||
|
||||
`useParty`
|
||||
----------
|
||||
`useParty` returns the party, for which commands are currently send to the ledger.
|
||||
|
||||
```typescript
|
||||
const party = useParty()
|
||||
```
|
||||
|
||||
`useExercise`
|
||||
-------------
|
||||
`useExercise` returns a function to exercise a choice by contract id.
|
||||
|
||||
```typescript
|
||||
const [exerciseChoice] = useExercise(ContractTemplate.ChoiceName)
|
||||
const onClick = () => exerciseChoice(contractId, argument)
|
||||
```
|
||||
|
||||
`useExerciseByKey`
|
||||
------------------
|
||||
`useExerciseByKey` returns a function to exercise a choice by contract key.
|
||||
|
||||
```typescript
|
||||
const [exerciseByKey] = useExerciseByKey(ContractTemplate.ChoiceName)
|
||||
const onClick = () => exerciseByKey(key, argument)
|
||||
```
|
||||
|
||||
`useQuery`
|
||||
----------
|
||||
`useQuery` returns the contracts matching a given query. The query matches for a given contract
|
||||
template and specified field values of the contracts of that template.
|
||||
|
||||
```typescript
|
||||
const {contracts, isLoading} = useQuery(ContractTemplate, () => {field: value}, [dependency1,
|
||||
dependency2, ...])
|
||||
```
|
||||
|
||||
`useReload`
|
||||
-----------
|
||||
`useReload` returns a function to reload the results of queries.
|
||||
|
||||
```typescript
|
||||
const reload = useReload()
|
||||
const onClick = reload
|
||||
```
|
||||
|
||||
`useStreamQuery`
|
||||
----------------
|
||||
`useStreamQuery` has the same signature as `useQuery`, but it constantly refreshes the results.
|
||||
|
||||
```typescript
|
||||
const {contracts, isLoading} = useStreamQuery(ContractTemplate, () => {field: value}, [dependency1,
|
||||
dependency2, ...])
|
||||
```
|
||||
|
||||
`useFetchByKey`
|
||||
---------------
|
||||
`useFetchByKey` returns the unique contract of a given template and a given contract key.
|
||||
|
||||
```typescript
|
||||
const {contract, isLoading} = useFetchByKey(ContractTemplate, () => key, [dependency1, dependency2, ...])
|
||||
```
|
||||
|
||||
`useStreamFetchByKey`
|
||||
---------------------
|
||||
`useStreamFetchByKey` has the same signature as `useFetchByKey`, but it constantly keeps refreshes
|
||||
the result.
|
||||
|
||||
```typescript
|
||||
const {contract, isLoading} = useStreamFetchByKey(ContractTemplate, () => key, [dependency1, dependency2, ...])
|
||||
```
|
||||
|
||||
|
||||
## Source
|
||||
https://github.com/digital-asset/daml.
|
||||
|
||||
@ -2,25 +2,20 @@
|
||||
|
||||
> Primitive types of the DAML language and their serialization.
|
||||
|
||||
## Install
|
||||
## Documentation
|
||||
|
||||
### npm:
|
||||
Comprehensive documentation for `@daml/types` can be found
|
||||
[here](https://docs.daml.com/app-dev/bindings-ts/daml-types/index.html).
|
||||
|
||||
```sh
|
||||
npm install @daml/types
|
||||
```
|
||||
## Description
|
||||
|
||||
### yarn:
|
||||
This library contains TypeScript types corresponding to primitive DAML data types, such as
|
||||
`Template`, `ContractId`, `Int`, `Text` etc. as well as their encoders and decoders to interact with
|
||||
the [JSON API](https://docs.daml.com/json-api/index.html) of a DAML ledger.
|
||||
|
||||
```sh
|
||||
yarn add @daml/types
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
For creating a DAML distributed application, you'll most likely want to use the [@daml/react](https://www.npmjs.com/package/@daml/react) and
|
||||
[@daml/ledger](https://www.npmjs.com/package/@daml/ledger) packages. The best place to get you started is [Create DAML App](https://github.com/digital-asset/create-daml-app)
|
||||
and the [Quickstart Guide](https://docs.daml.com/getting-started/quickstart.html).
|
||||
For creating a DAML distributed application, you'll most likely want to use the
|
||||
[@daml/react](https://www.npmjs.com/package/@daml/react) and
|
||||
[@daml/ledger](https://www.npmjs.com/package/@daml/ledger) packages.
|
||||
|
||||
## Source
|
||||
https://github.com/digital-asset/daml.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user