メインコンテンツへスキップ

ユーティリティ

@blocklet/did-space-js ライブラリは、アプリケーションの構築中に遭遇する一般的なタスクを簡素化するために設計されたユーティリティ関数のコレクションをエクスポートします。これらのヘルパーは、DID のフォーマット、URL の正規化、エンコーディング、エラー解析などの操作を処理するため、コアアプリケーションロジックに集中できます。

これらのユーティリティはパッケージから直接インポートできます：

Import Utilities

typescript
import {
  toABTDid,
  toDid,
  normalizeEndpoint,
  getSpaceServiceEndpoint,
  encode,
  getErrorMessage,
  getErrorStatusCode,
} from '@blocklet/did-space-js';

DIDフォーマット

DID Space は did:abt: プレフィックスを持つ DID を使用します。これらのユーティリティは、標準 DID と ABT 固有のフォーマット間の変換を支援し、互換性と適切な検証を保証します。

toABTDid

有効な DID 文字列に did:abt: プレフィックスを追加します。これは、ベース DID から完全な ABT DID を構築する必要がある場合に便利です。

パラメータ

  • did string (required) — 有効な標準 DID 文字列。

戻り値

  • abtDid string — 'did:abt:' がプレフィックスとして付加された DID 文字列。

例

toABTDid Example

typescript
import { toABTDid } from '@blocklet/did-space-js';

const baseDid = 'z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr';
const abtDid = toABTDid(baseDid);

console.log(abtDid); // "did:abt:z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr"

try {
  toABTDid('invalid-did');
} catch (error) {
  console.error(error.message); // "did(invalid-did) is not a valid did"
}

toDid

DID 文字列から did:abt: プレフィックスを削除し、ベース DID を返します。また、結果の文字列が有効な DID であることも検証します。

パラメータ

  • did string (required) — 通常は 'did:abt:' プレフィックスが付いた DID 文字列。

戻り値

  • baseDid string — プレフィックスなしのベース DID 文字列。

例

toDid Example

typescript
import { toDid } from '@blocklet/did-space-js';

const abtDid = 'did:abt:z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr';
const baseDid = toDid(abtDid);

console.log(baseDid); // "z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr"

try {
  toDid('did:abt:invalid-did');
} catch (error) {
  console.error(error.message); // "did(invalid-did) is not a valid did"
}

エンドポイントとURLユーティリティ

これらの関数は、DID Space との通信に必要なエンドポイントの管理と解決を支援します。

normalizeEndpoint

クエリパラメータと末尾の /object/ セグメントを削除して DID Space エンドポイント URL をクリーンアップします。これにより、API 呼び出しのための一貫したベース URL を確保できます。

パラメータ

  • endpoint string (required) — 完全な DID Space エンドポイント URL。

戻り値

  • normalizedEndpoint string — クリーンアップされたベースエンドポイント URL。

例

normalizeEndpoint Example

typescript
import { normalizeEndpoint } from '@blocklet/did-space-js';

const fullEndpoint =
  'https://73aa3e87-znkjt5vbgnezh4p6v4dsaye61e7pxxn3vk4j.did.abtnet.io/app/api/space/z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr/app/zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F/object/?some=query';
const normalized = normalizeEndpoint(fullEndpoint);

console.log(normalized); // "https://73aa3e87-znkjt5vbgnezh4p6v4dsaye61e7pxxn3vk4j.did.abtnet.io/app/api/space/z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr/app/zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F/"

getSpaceServiceEndpoint

指定された DID Space の実際のサービスエンドポイントを解決します。一部のスペースは、ファイル操作のために別のサービス URL にリダイレクトするゲートウェイ URL を使用する場合があります。この関数は、その解決を処理します。

パラメータ

  • normalizedEndpoint string (required) — 正規化された DID Space エンドポイント URL。通常は normalizeEndpoint から取得します。
  • defaultValue string — エンドポイントが解決できない場合に返すフォールバック値。デフォルトでは normalizedEndpoint 自体になります。

戻り値

  • serviceEndpoint Promise<string> — 実際のサービスエンドポイント URL に解決されるプロミス。

例

getSpaceServiceEndpoint Example

typescript
import { getSpaceServiceEndpoint } from '@blocklet/did-space-js';

async function resolveEndpoint(endpoint: string) {
  const serviceEndpoint = await getSpaceServiceEndpoint(endpoint);
  console.log(`Service URL for ${endpoint} is ${serviceEndpoint}`);
}

const spaceUrl =
  'https://73aa3e87-znkjt5vbgnezh4p6v4dsaye61e7pxxn3vk4j.did.abtnet.io/app/api/space/z3T6WZD3dBtaVUgwb3rtBey8BartrJDTLrmQr/app/zNKsSUmUVJntiVdAPpg8vYtEgnFvSppYLf4F/';
resolveEndpoint(spaceUrl);

エンコーディング

encode

文字列を URL セーフな Base64 形式にエンコードします。これは、URL で使用されるファイルパスやキーをエンコードするのに特に便利で、特殊文字が問題を引き起こさないようにします。

パラメータ

  • key string (required) — エンコードする文字列（ファイルパスなど）。

戻り値

  • encodedKey string — URL セーフな Base64 でエンコードされた文字列。

例

encode Example

typescript
import { encode } from '@blocklet/did-space-js';

const filePath = 'path/to/my important file.txt';
const encodedPath = encode(filePath);

console.log(encodedPath); // "cGF0aC90by9teSBpbXBvcnRhbnQgZmlsZS50eHQ"

エラーハンドリング

API 呼び出しが失敗すると、SDK はエラーをスローします。これらのユーティリティ関数は、エラーオブジェクトを解析して人間が読めるメッセージと HTTP ステータスコードを抽出し、エラーハンドリングロジックを簡素化するのに役立ちます。

getErrorMessage

基盤となる HTTP クライアント（got）によってスローされる可能性のあるさまざまなタイプのエラーオブジェクトから、最も関連性の高いエラーメッセージを抽出します。

パラメータ

  • error Error | RequestError (required) — catch ブロックでキャッチされたエラーオブジェクト。

戻り値

  • errorMessage string — ユーザーフレンドリーなエラーメッセージ。

getErrorStatusCode

HTTP エラーオブジェクトから HTTP ステータスコードを抽出します。

パラメータ

  • error HTTPError (required) — catch ブロックでキャッチされたエラーオブジェクト。

戻り値

  • statusCode number — HTTP ステータスコード（例：404, 500）。

例

Error Handling Example

typescript
import { SpaceClient, GetObjectCommand } from '@blocklet/did-space-js';
import { getErrorMessage, getErrorStatusCode } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

const wallet = getWallet();
const client = new SpaceClient({
  endpoint: 'https://www.didspaces.com/app/api/space/...',
  wallet,
});

async function fetchNonExistentFile() {
  try {
    const command = new GetObjectCommand({ key: 'non-existent-file.txt' });
    await client.send(command);
  } catch (error) {
    const message = getErrorMessage(error);
    const statusCode = getErrorStatusCode(error);

    console.error(`Operation failed with status ${statusCode}: ${message}`);
    // 期待される出力例: "Operation failed with status 404: Not Found"
  }
}

fetchNonExistentFile();

この例では、try...catch ブロック内で getErrorMessage と getErrorStatusCode を使用して、ファイルが見つからないなどの API エラーを適切に処理する方法を示しています。

これらのユーティリティを使用すると、DID Space と対話する際に必要な一般的なデータ変換やエラーハンドリングシナリオの多くを処理できます。これらがより複雑なシナリオでどのように使用されるかを確認するには、API リファレンス をご覧ください。