TypeScript

این صفحه از انگلیسی ترجمه شده است. اگر این دو با هم تفاوت داشته باشند، صفحهٔ انگلیسی درست است. خواندن صفحهٔ انگلیسی

کتابخانه TypeScript همان بسته @lingara/api در npm است. روی Node.js 22 یا بالاتر اجرا می‌شود، هیچ وابستگی زمان اجرا ندارد، و برای هر درخواست، پاسخ و رویداد جریان تعریف نوع همراه دارد.

کجا اجرا می‌شود

این یک کتابخانه سمت سرور است. نسخه‌ای برای مرورگر وجود ندارد، و کلاینت وقتی خود را درون یک صفحه وب بیابد رمز کلاینت را نمی‌پذیرد: رمز کلاینت در مرورگر رمزی منتشرشده است که هر کسی صفحه را باز کند می‌تواند بخواند. API را از سرور خودتان فراخوانی کنید و فقط آنچه کاربرانتان نیاز دارند برایشان بفرستید.

در عمل چگونه است

• هر فراخوانی یک Promise برمی‌گرداند. برای لغو یک فراخوانی، { signal } را همراه یک AbortSignal بفرستید؛ آنگاه فراخوانی با دلیل خود همان سیگنال رد می‌شود.
• جریان یک پیمایش‌پذیر ناهمگام است که با for await خوانده می‌شود. تنبل است: درخواست زمانی فرستاده می‌شود که نخستین رویداد را بخواهید.
• خطاها از LingaraError ارث می‌برند، پس یک بررسی instanceof هر چهار را می‌گیرد. هر کدام وقتی API مدت انتظاری اعلام کرده باشد retryAfter را در خود دارد.
• برای استفاده از پشته HTTP خودتان، یک تابع fetch در گزینه‌ها بدهید. مهلت بیکاری جریان‌ها همچنان اعمال می‌شود.

نمونه‌های زیر بسته را نصب می‌کنند، یک کلاینت می‌سازند، فهرستی از واژگان را جریانی دریافت می‌کنند و یک خطا را مدیریت می‌کنند.

npm install @lingara/api@0.1.0-alpha.6

import { Lingara } from "@lingara/api";

const client = new Lingara({
  clientId: process.env.LINGARA_CLIENT_ID!,
  clientSecret: process.env.LINGARA_CLIENT_SECRET!,
});

const stream = client.generateVocabulary({ level: 2, source_lang: "en", target_lang: "zh", count: 8 });
for await (const ev of stream) {
  if (ev.event === "item") console.log(ev.data.word, ev.data.translation);
}

import { ApiError, MaintenanceError, OAuthError, TransportError } from "@lingara/api";

try {
  await client.getUsage();
} catch (e) {
  if (e instanceof ApiError) {
    // A refusal from the API: e.status, e.code (stable) and e.message (localised).
    console.error(e.status, e.code, e.message, e.retryAfter ?? "");
  } else if (e instanceof OAuthError) {
    // The token endpoint refused the credentials or the scopes.
    console.error(e.status, e.error, e.description ?? "");
  } else if (e instanceof MaintenanceError) {
    console.error("under maintenance; retry after", e.retryAfter ?? "a while");
  } else if (e instanceof TransportError) {
    // No usable answer: connect, tls, reset, timeout, and so on.
    console.error("transport:", e.kind);
  } else {
    throw e;
  }
}