Publish preparations (#206)

Author: 0x009922

.gitignore

@@ -14,4 +14,5 @@ v8-compile-cache-0
 /packages/crypto-target-*/wasm-target
 /packages/core/crypto/wasm-target
 **/*_generated_.ts
+/packages/core/data-model/schema/schema.json
 

CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to Iroha JavaScript
+
+This document explains how this repo works, and how to work with it.
+
+Steps, in short:
+
+1. Install Rust and `wasm-pack`.
+2. Install Deno v2 and Node.js v22
+3. Link Iroha repository
+4. Explore `tasks` in the root `deno.json`
+5. Work with the code
+
+TODO: setting up commit hooks
+
+## Installing Rust and `wasm-pack`
+
+```sh
+# install rustup
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+# add necessary components
+rustup component add rust-src --target wasm32-unknown-unknown
+
+# install wasm-pack
+curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+```
+
+## Installing Deno & Node.js
+
+This must be pretty straightforward. A few notes though:
+
+- While this project is mostly driven by Deno, there are some Node.js parts, unfortunately. Specifically,
+  `tests/browser` is a `pnpm` project, because otherwise it's hard to make Cypress work.
+- Thus, run `corepack enable` (or install `npm i -g pnpm`) so that `pnpm` is also available.
+
+## Linking & building Iroha
+
+For this project to function, you must link Iroha repository. There are two ways to do so:
+
+```sh
+# symlink to the local path
+deno task prep:iroha --path /path/to/local/iroha/clone
+```
+
+```sh
+# clone the repo
+deno task prep:iroha --git https://github.com/hyperledger-iroha/iroha.git --rev v2.0.0-rc.1.0
+```
+
+After Iroha is linked, you need to prepare some artifacts from it (binaries such as `irohad`, `kagami`, `iroha_codec`;
+`executor.wasm`; `schema.json`):
+
+```sh
+deno task prep:iroha:build
+```
+
+## Running tests
+
+Please explore `tasks` in the root `deno.jsonc`.
+
+```sh
+# run them all
+deno task test
+
+# unit, non-integration tests
+deno run npm:vitest
+# or
+pnpm dlx vitest
+```
+
+Tests are mostly written in Vitest (except the doctests), and it doesn't work very well with Deno (considering
+migration). To improve development experience, consider running Vitest via `pnpm dlx` or similar.

README.md

@@ -1,5 +1,54 @@
 # Iroha JavaScript
 
-This is a JavaScript (TypeScript) SDK for Iroha 2.
+The JavaScript (TypeScript) SDK of [Iroha 2](https://github.com/hyperledger-iroha/iroha).
 
-TODO
+Works in Deno, Node.js, and the Browser. (TODO: check in Bun and Cloudflare Workers).
+
+Packages and documentation are available on JSR: https://jsr.io/@iroha
+
+## Usage
+
+### Installation
+
+```shell
+# deno
+deno add jsr:@iroha/core
+
+# npm (one of the below, depending on your package manager)
+npx jsr add @iroha/core
+yarn dlx jsr add @iroha/core
+pnpm dlx jsr add @iroha/core
+bunx jsr add @iroha/core
+```
+
+### Quick Example
+
+```ts
+import '@iroha/crypto-target-node/install'
+import { Client } from '@iroha/client'
+import * as types from '@iroha/core/data-model'
+
+const kp = types.KeyPair.random()
+
+const client = new Client({
+  toriiBaseURL: new URL('http://localhost:8080'),
+  chain: '000-000',
+  accountDomain: new types.Name('wonderland'),
+  accountKeyPair: kp,
+})
+
+async function test() {
+  const { blocks } = await client.api.telemetry.status()
+  console.log(blocks) // => 3
+}
+```
+
+This example assumes running in Deno/Node.js.
+
+## Iroha Compatibility
+
+See the ["Compatibility" secion in `@iroha/core` package documentation](https://jsr.io/@iroha/core#iroha-compatibility).
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md)

deno.jsonc

@@ -1,10 +1,13 @@
 {
+  "license": "Apache 2.0",
   "nodeModulesDir": "auto",
+  "exclude": ["**/docs"],
   "workspace": [
     "./packages/core",
     "./packages/crypto-target-node",
     "./packages/crypto-target-web",
     "./packages/client",
+    "./packages/client-web-socket-node",
 
     "./tests/support/test-configuration",
     "./tests/support/test-peer",
@@ -24,15 +27,19 @@
     },
     "prep:crypto-wasm": "deno run --allow-read --allow-env --allow-run --allow-write ./etc/task-prep-crypto-wasm.ts",
     "prep:crypto-wasm:copy": "deno task prep:crypto-wasm --onlyCopy",
-    "prep:codegen": "deno run --allow-write --allow-read ./etc/task-codegen.ts",
+    "prep:codegen": {
+      "command": "deno run --allow-write --allow-read ./etc/task-codegen.ts",
+      "dependencies": ["prep:iroha:check"]
+    },
     "prep:codegen:watch": "watchexec -e ts deno task prep:codegen",
     "prep:ensure-ready": {
       "dependencies": ["prep:codegen", "prep:crypto-wasm:copy", "prep:iroha:check"]
     },
     "check:all": {
-      "command": "deno check .",
+      "command": "deno check --doc .",
       "dependencies": ["prep:ensure-ready"]
     },
+    "test:deno": "deno test --doc --allow-read",
     "test:vitest": {
       "dependencies": ["prep:ensure-ready"],
       "description": "Run Vitest",
@@ -48,7 +55,7 @@
     },
     "test": {
       "description": "Run all tests, from unit to integration",
-      "command": "deno task test:vitest && deno task test:integration:node && deno task test:integration:browser"
+      "command": "deno task test:deno && deno task test:vitest && deno task test:integration:node && deno task test:integration:browser"
     },
     "dev:run-test-peer": {
       "dependencies": ["prep:ensure-ready"],
@@ -98,7 +105,10 @@
   "publish": {
     "exclude": [
       "!**/*_generated_.ts",
-      "!packages/crypto-target-*/wasm-target"
+      "!packages/crypto-target-*/wasm-target",
+      "!packages/core/crypto/wasm-target",
+      "!packages/core/data-model/schema/schema.json"
     ]
-  }
+  },
+  "test": { "exclude": ["prep", "crypto-wasm"] }
 }

deno.lock

@@ -11,19 +11,20 @@ const tsFormatter = dprint.createFromBuffer(await Deno.readFile(dprintTS.getPath
 const formatTS = (code: string) => tsFormatter.formatText({ filePath: 'file.ts', fileText: code })
 
 async function write({ file, code }: { file: string; code: string }) {
+  let status: string
   try {
     const prevCode = await Deno.readTextFile(file)
     if (prevCode === code) {
-      $.logStep(`Skipping ${colors.cyan(file)}, no change`)
-      return
+      status = 'unchanged'
     } else {
       await Deno.writeTextFile(file, code)
-      $.logStep(`Re-written ${colors.cyan(file)}`)
+      status = 'updated'
     }
   } catch {
     await Deno.writeTextFile(file, code)
-    $.logStep(`Written ${colors.cyan(file)}`)
+    status = 'created'
   }
+  $.logStep(`Generated ${colors.cyan(file)} (${status})`)
 }
 
 /**

etc/task-codegen.ts

@@ -82,6 +82,21 @@ async function copyArtifacts() {
   $.logStep(`Finished copying artifacts to ${colors.bold(colors.cyan(PREP_OUTPUT_DIR))}`)
 }
 
+async function copySchemaJson() {
+  const dest = resolveFromRoot('packages/core/data-model/schema/schema.json')
+
+  try {
+    await Deno.remove(dest)
+  } catch (err) {
+    if (!(err instanceof Deno.errors.NotFound)) {
+      throw err
+    }
+  }
+
+  await copy(path.join(PREP_OUTPUT_DIR, 'schema.json'), dest)
+  $.logStep('Copied', dest)
+}
+
 const args = parseArgs(Deno.args, {
   string: ['git', 'git-rev', 'path'],
   boolean: ['check', 'build'],
@@ -100,6 +115,7 @@ await match(args)
   .with({ check: true }, async () => {
     if (await dirExists(PREP_OUTPUT_DIR)) {
       $.logStep(`Checked that ${colors.cyan(PREP_OUTPUT_DIR)} exists`)
+      await copySchemaJson()
     } else {
       $.logError(
         `Error: ${PREP_OUTPUT_DIR} doesn't exist. Make sure to run ${

etc/task-prep-iroha.ts

@@ -6,6 +6,7 @@ const PATHS = [
   'packages/crypto-target-node',
   'packages/crypto-target-web',
   'packages/client',
+  'packages/client-web-socket-node',
 ].map(
   (x) => resolveFromRoot(x),
 )

etc/task-publish.ts

@@ -0,0 +1,8 @@
+{
+  "name": "@iroha/client-web-socket-node",
+  "version": "0.1.0",
+  "exports": "./mod.ts",
+  "imports": {
+    "ws": "npm:ws@^8.18.0"
+  }
+}

packages/client-web-socket-node/deno.jsonc

@@ -1,4 +1,18 @@
-import type { IncomingData, IsomorphicWebSocketAdapter } from './types.ts'
+/**
+ * WebSocket adapter for Node.js environment. Build on top of `npm:ws`.
+ *
+ * @example
+ * ```ts
+ * import ws from '@iroha/client-web-socket-node'
+ * import { WebSocketAPI } from '@iroha/client'
+ *
+ * new WebSocketAPI(new URL('http://localhost:8080'), ws)
+ * ```
+ *
+ * @module
+ */
+
+import type { IncomingData, IsomorphicWebSocketAdapter } from '@iroha/client/web-socket'
 import WebSocket from 'ws'
 import { Buffer } from 'node:buffer'
 
@@ -13,7 +27,10 @@ function handleIncomingData(
   throw new Error('Unable to parse incoming data')
 }
 
-export const adapter: IsomorphicWebSocketAdapter = {
+/**
+ * The WebSocket adapter.
+ */
+const adapter: IsomorphicWebSocketAdapter = {
   initWebSocket: (params) => {
     const socket = new WebSocket(params.url)
 
@@ -33,3 +50,5 @@ export const adapter: IsomorphicWebSocketAdapter = {
     }
   },
 }
+
+export default adapter