From 9791f8faae4cc9e0276184c8595395e5e0955a32 Mon Sep 17 00:00:00 2001 From: Alina Sireneva Date: Fri, 27 Oct 2023 14:25:21 +0300 Subject: [PATCH] docs: updated typedoc, added ci, fixed some docs --- .github/workflows/docs.yaml | 37 ++++++++++ .gitignore | 6 +- package.json | 2 +- packages/client/src/types/bots/keyboards.ts | 1 + packages/client/src/types/media/audio.ts | 3 + packages/client/src/types/media/document.ts | 1 + .../client/src/types/media/input-media.ts | 1 + .../src/types/misc/input-privacy-rule.ts | 4 +- .../src/types/peers/chat-event/index.ts | 2 +- .../client/src/types/stories/all-stories.ts | 6 +- .../src/types/stories/interactive/index.ts | 1 + packages/client/typedoc.cjs | 8 +++ packages/client/typedoc.js | 16 ----- packages/core/package.json | 3 +- packages/core/src/base-client.ts | 11 ++- packages/core/src/network/config-manager.ts | 6 ++ packages/core/src/network/network-manager.ts | 15 +++++ .../core/src/network/transports/abstract.ts | 1 + packages/core/src/storage/abstract.ts | 14 +++- packages/core/tsconfig.json | 16 +---- packages/core/typedoc.cjs | 12 ++++ packages/core/typedoc.js | 17 ----- packages/crypto-node/typedoc.cjs | 4 ++ packages/crypto-node/typedoc.js | 11 --- packages/dispatcher/src/dispatcher.ts | 2 +- packages/dispatcher/typedoc.cjs | 4 ++ packages/dispatcher/typedoc.js | 11 --- packages/file-id/typedoc.cjs | 4 ++ packages/file-id/typedoc.js | 11 --- packages/html-parser/typedoc.cjs | 4 ++ packages/html-parser/typedoc.js | 11 --- packages/http-proxy/index.ts | 2 +- packages/http-proxy/typedoc.cjs | 4 ++ packages/http-proxy/typedoc.js | 11 --- packages/i18n/package.json | 4 ++ packages/i18n/typedoc.cjs | 7 ++ packages/i18n/typedoc.js | 15 ----- packages/markdown-parser/typedoc.cjs | 4 ++ packages/markdown-parser/typedoc.js | 11 --- packages/mtproxy/typedoc.cjs | 4 ++ packages/mtproxy/typedoc.js | 11 --- packages/node/typedoc.cjs | 11 +++ packages/node/typedoc.js | 22 ------ packages/socks-proxy/index.ts | 2 +- packages/socks-proxy/typedoc.cjs | 4 ++ packages/socks-proxy/typedoc.js | 11 --- packages/sqlite/typedoc.cjs | 4 ++ packages/sqlite/typedoc.js | 11 --- packages/tl-runtime/typedoc.cjs | 4 ++ packages/tl-runtime/typedoc.js | 12 ---- packages/tl-utils/typedoc.cjs | 4 ++ packages/tl-utils/typedoc.js | 11 --- pnpm-lock.yaml | 52 ++++++++++++-- scripts/typedoc-external-links.cjs | 67 +++++++++++++++++++ typedoc.base.cjs | 19 ++++++ typedoc.cjs | 14 ++++ typedoc.js | 16 ----- 57 files changed, 338 insertions(+), 244 deletions(-) create mode 100644 .github/workflows/docs.yaml create mode 100644 packages/client/typedoc.cjs delete mode 100644 packages/client/typedoc.js create mode 100644 packages/core/typedoc.cjs delete mode 100644 packages/core/typedoc.js create mode 100644 packages/crypto-node/typedoc.cjs delete mode 100644 packages/crypto-node/typedoc.js create mode 100644 packages/dispatcher/typedoc.cjs delete mode 100644 packages/dispatcher/typedoc.js create mode 100644 packages/file-id/typedoc.cjs delete mode 100644 packages/file-id/typedoc.js create mode 100644 packages/html-parser/typedoc.cjs delete mode 100644 packages/html-parser/typedoc.js create mode 100644 packages/http-proxy/typedoc.cjs delete mode 100644 packages/http-proxy/typedoc.js create mode 100644 packages/i18n/typedoc.cjs delete mode 100644 packages/i18n/typedoc.js create mode 100644 packages/markdown-parser/typedoc.cjs delete mode 100644 packages/markdown-parser/typedoc.js create mode 100644 packages/mtproxy/typedoc.cjs delete mode 100644 packages/mtproxy/typedoc.js create mode 100644 packages/node/typedoc.cjs delete mode 100644 packages/node/typedoc.js create mode 100644 packages/socks-proxy/typedoc.cjs delete mode 100644 packages/socks-proxy/typedoc.js create mode 100644 packages/sqlite/typedoc.cjs delete mode 100644 packages/sqlite/typedoc.js create mode 100644 packages/tl-runtime/typedoc.cjs delete mode 100644 packages/tl-runtime/typedoc.js create mode 100644 packages/tl-utils/typedoc.cjs delete mode 100644 packages/tl-utils/typedoc.js create mode 100644 scripts/typedoc-external-links.cjs create mode 100644 typedoc.base.cjs create mode 100644 typedoc.cjs delete mode 100644 typedoc.js diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 00000000..5eb7e87f --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,37 @@ +name: Docs + +on: + push: + branches: + - master + workflow_dispatch: + +jobs: + build-docs: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v3 + - name: Set up Node + uses: actions/setup-node@v3 + with: + node-version: "18" + - name: Setup pnpm + uses: pnpm/action-setup@v2 + with: + version: 8 + - run: pnpm install --frozen-lockfile + - name: 'TL codegen' + run: pnpm -C packages/tl run gen-code + - name: Build + run: pnpm run -r build + - name: Build docs + run: | + pnpm run docs + touch docs/.nojekyll + echo "ref.mtcute.dev" > docs/CNAME + - name: Deploy + uses: JamesIves/github-pages-deploy-action@v4.4.1 + with: + branch: gh-pages + folder: docs \ No newline at end of file diff --git a/.gitignore b/.gitignore index e9923809..800562bb 100644 --- a/.gitignore +++ b/.gitignore @@ -7,9 +7,7 @@ private/ .vscode *.log -# Docs are generated and deployed in gh-pages branch. - -docs/* -!docs/.nojekyll +# docs are generated in ci +docs *.tsbuildinfo \ No newline at end of file diff --git a/package.json b/package.json index 4b727080..087d2c8d 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,7 @@ "lint:fix": "eslint --fix .", "format": "prettier --write \"packages/**/*.ts\"", "publish-all": "node scripts/publish.js all", - "docs": "pnpm run -r docs", + "docs": "typedoc", "build-package": "node scripts/build-package.js" }, "dependencies": { diff --git a/packages/client/src/types/bots/keyboards.ts b/packages/client/src/types/bots/keyboards.ts index 2c72297e..acb03b45 100644 --- a/packages/client/src/types/bots/keyboards.ts +++ b/packages/client/src/types/bots/keyboards.ts @@ -61,6 +61,7 @@ export type ReplyMarkup = */ // eslint-disable-next-line @typescript-eslint/no-namespace export namespace BotKeyboard { + /** Create a keyboard builder */ export function builder(maxRowWidth?: number | null): BotKeyboardBuilder { return new BotKeyboardBuilder(maxRowWidth) } diff --git a/packages/client/src/types/media/audio.ts b/packages/client/src/types/media/audio.ts index 4ce977c5..1b201fb7 100644 --- a/packages/client/src/types/media/audio.ts +++ b/packages/client/src/types/media/audio.ts @@ -9,14 +9,17 @@ import { RawDocument } from './document.js' * An audio file */ export class Audio extends RawDocument { + /** Type of the media (for use in a tagged union) */ readonly type = 'audio' as const + /** Type of the file for File ID generation */ protected _fileIdType(): tdFileId.FileType { return tdFileId.FileType.Audio } constructor( doc: tl.RawDocument, + /** TL object describing the audio */ readonly attr: tl.RawDocumentAttributeAudio, ) { super(doc) diff --git a/packages/client/src/types/media/document.ts b/packages/client/src/types/media/document.ts index a4311191..14a3431f 100644 --- a/packages/client/src/types/media/document.ts +++ b/packages/client/src/types/media/document.ts @@ -12,6 +12,7 @@ import { Thumbnail } from './thumbnail.js' * This also includes audios, videos, voices etc. */ export abstract class RawDocument extends FileLocation { + /** Type of the media (for use in a tagged union) */ abstract type: string constructor(readonly raw: tl.RawDocument) { diff --git a/packages/client/src/types/media/input-media.ts b/packages/client/src/types/media/input-media.ts index 1635f457..9e10f93b 100644 --- a/packages/client/src/types/media/input-media.ts +++ b/packages/client/src/types/media/input-media.ts @@ -598,6 +598,7 @@ export type InputMediaLike = // eslint-disable-next-line @typescript-eslint/no-namespace export namespace InputMedia { + /** Omit `type` and `file` from the given type */ export type OmitTypeAndFile = Omit /** diff --git a/packages/client/src/types/misc/input-privacy-rule.ts b/packages/client/src/types/misc/input-privacy-rule.ts index 6f9eef8e..a1ffb5a2 100644 --- a/packages/client/src/types/misc/input-privacy-rule.ts +++ b/packages/client/src/types/misc/input-privacy-rule.ts @@ -4,12 +4,12 @@ import { MaybeArray, tl } from '@mtcute/core' import { InputPeerLike } from '../peers/index.js' -interface InputPrivacyRuleUsers { +export interface InputPrivacyRuleUsers { allow: boolean users: InputPeerLike[] } -interface InputPrivacyRuleChatParticipants { +export interface InputPrivacyRuleChatParticipants { allow: boolean chats: InputPeerLike[] } diff --git a/packages/client/src/types/peers/chat-event/index.ts b/packages/client/src/types/peers/chat-event/index.ts index 6296feda..1875fde3 100644 --- a/packages/client/src/types/peers/chat-event/index.ts +++ b/packages/client/src/types/peers/chat-event/index.ts @@ -7,7 +7,7 @@ import { User } from '../user.js' import { _actionFromTl, ChatAction } from './actions.js' export * from './actions.js' -export { InputChatEventFilters } from './filters.js' +export { ChatEventFilters, InputChatEventFilters } from './filters.js' export class ChatEvent { constructor( diff --git a/packages/client/src/types/stories/all-stories.ts b/packages/client/src/types/stories/all-stories.ts index 4d5dca38..23f3747d 100644 --- a/packages/client/src/types/stories/all-stories.ts +++ b/packages/client/src/types/stories/all-stories.ts @@ -12,8 +12,12 @@ import { StoriesStealthMode } from './stealth-mode.js' * Returned by {@link TelegramClient.getAllStories} */ export class AllStories { - constructor(readonly raw: tl.stories.RawAllStories) {} + constructor( + /** Raw TL object */ + readonly raw: tl.stories.RawAllStories, + ) {} + /** Peers index */ readonly _peers = PeersIndex.from(this.raw) /** Whether there are more stories to fetch */ diff --git a/packages/client/src/types/stories/interactive/index.ts b/packages/client/src/types/stories/interactive/index.ts index 070d88d1..5a4d88d9 100644 --- a/packages/client/src/types/stories/interactive/index.ts +++ b/packages/client/src/types/stories/interactive/index.ts @@ -5,6 +5,7 @@ import { StoryInteractiveReaction } from './reaction.js' import { StoryInteractiveVenue } from './venue.js' export * from './input.js' +export { StoryInteractiveLocation, StoryInteractiveReaction, StoryInteractiveVenue } export type StoryInteractiveElement = StoryInteractiveReaction | StoryInteractiveLocation | StoryInteractiveVenue diff --git a/packages/client/typedoc.cjs b/packages/client/typedoc.cjs new file mode 100644 index 00000000..9ffc29d1 --- /dev/null +++ b/packages/client/typedoc.cjs @@ -0,0 +1,8 @@ +module.exports = { + extends: ['../../typedoc.base.cjs'], + entryPoints: [ + './src/index.ts', + './src/utils/index.ts', + ], + entryPointStrategy: 'expand', +} diff --git a/packages/client/typedoc.js b/packages/client/typedoc.js deleted file mode 100644 index 54bd13d7..00000000 --- a/packages/client/typedoc.js +++ /dev/null @@ -1,16 +0,0 @@ -const path = require('path') - -module.exports = { - ...require('../../typedoc.js'), - out: path.join( - __dirname, - '../../docs/packages/' + - require('./package.json').name.replace(/^@.+\//, ''), - ), - entryPoints: ['./src/index.ts'], - excludeExternals: true, - externalPattern: [ - '../tl/**/*', - '**/*/node_modules/**/*', - ], -} diff --git a/packages/core/package.json b/packages/core/package.json index a8e3cad3..bd9614d3 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -9,8 +9,7 @@ "type": "module", "scripts": { "test": "mocha \"tests/**/*.spec.ts\"", - "build": "pnpm run -w build-package core", - "docs": "typedoc" + "build": "pnpm run -w build-package core" }, "browser": { "./cjs/utils/platform/crypto.js": "./cjs/utils/platform/crypto.web.js", diff --git a/packages/core/src/base-client.ts b/packages/core/src/base-client.ts index 27222a0a..c24d4462 100644 --- a/packages/core/src/base-client.ts +++ b/packages/core/src/base-client.ts @@ -30,6 +30,7 @@ import { writeStringSession, } from './utils/index.js' +/** Options for {@link BaseTelegramClient} */ export interface BaseTelegramClientOptions { /** * API ID from my.telegram.org @@ -193,6 +194,10 @@ export interface BaseTelegramClientOptions { writerMap?: TlWriterMap } +/** + * Basic Telegram client that only implements the bare minimum + * to make RPC calls and receive low-level updates. + */ export class BaseTelegramClient extends EventEmitter { /** * Crypto provider taken from {@link BaseTelegramClientOptions.crypto} @@ -226,13 +231,17 @@ export class BaseTelegramClient extends EventEmitter { protected _defaultDcs: ITelegramStorage.DcOptions private _niceStacks: boolean + /** TL layer used by the client */ readonly _layer: number + /** TL readers map used by the client */ readonly _readerMap: TlReaderMap + /** TL writers map used by the client */ readonly _writerMap: TlWriterMap + /** Unix timestamp when the last update was received */ protected _lastUpdateTime = 0 - protected _config = new ConfigManager(() => this.call({ _: 'help.getConfig' })) + readonly _config = new ConfigManager(() => this.call({ _: 'help.getConfig' })) // not really connected, but rather "connect() was called" private _connected: ControllablePromise | boolean = false diff --git a/packages/core/src/network/config-manager.ts b/packages/core/src/network/config-manager.ts index b0338048..ce182bdc 100644 --- a/packages/core/src/network/config-manager.ts +++ b/packages/core/src/network/config-manager.ts @@ -1,5 +1,11 @@ import { tl } from '@mtcute/tl' +/** + * Config manager is responsible for keeping + * the current server configuration up-to-date + * and providing methods to find the best DC + * option for the current session. + */ export class ConfigManager { constructor(private _update: () => Promise) {} diff --git a/packages/core/src/network/network-manager.ts b/packages/core/src/network/network-manager.ts index 5805e61a..217b0c98 100644 --- a/packages/core/src/network/network-manager.ts +++ b/packages/core/src/network/network-manager.ts @@ -96,6 +96,7 @@ export interface NetworkManagerExtraParams { inactivityTimeout?: number } +/** Options that can be customized when making an RPC call */ export interface RpcCallOptions { /** * If the call results in a `FLOOD_WAIT_X` error, @@ -146,6 +147,9 @@ export interface RpcCallOptions { abortSignal?: AbortSignal } +/** + * Wrapper over all connection pools for a single DC. + */ export class DcConnectionManager { private __baseConnectionParams = (): SessionConnectionParams => ({ crypto: this.manager.params.crypto, @@ -167,8 +171,10 @@ export class DcConnectionManager { private _log = this.manager._log.create('dc-manager') + /** Main connection pool */ main: MultiSessionConnection + /** Upload connection pool */ upload = new MultiSessionConnection( this.__baseConnectionParams(), this.manager._connectionCount('upload', this.dcId, this.manager.params.isPremium), @@ -176,6 +182,7 @@ export class DcConnectionManager { 'UPLOAD', ) + /** Download connection pool */ download = new MultiSessionConnection( this.__baseConnectionParams(), this.manager._connectionCount('download', this.dcId, this.manager.params.isPremium), @@ -183,6 +190,7 @@ export class DcConnectionManager { 'DOWNLOAD', ) + /** Download connection pool (for small files) */ downloadSmall = new MultiSessionConnection( this.__baseConnectionParams(), this.manager._connectionCount('downloadSmall', this.dcId, this.manager.params.isPremium), @@ -197,9 +205,13 @@ export class DcConnectionManager { } constructor( + /** Network manager instance */ readonly manager: NetworkManager, + /** DC ID */ readonly dcId: number, + /** DC options to use */ readonly _dcs: ITelegramStorage.DcOptions, + /** Whether this DC is the primary one */ public isPrimary = false, ) { this._log.prefix = `[DC ${dcId}] ` @@ -349,6 +361,9 @@ export class DcConnectionManager { } } +/** + * Class that manages all connections to Telegram servers. + */ export class NetworkManager { readonly _log = this.params.log.create('network') readonly _storage = this.params.storage diff --git a/packages/core/src/network/transports/abstract.ts b/packages/core/src/network/transports/abstract.ts index dcd79e09..a78b63da 100644 --- a/packages/core/src/network/transports/abstract.ts +++ b/packages/core/src/network/transports/abstract.ts @@ -5,6 +5,7 @@ import { tl } from '@mtcute/tl' import { MaybeAsync } from '../../types/index.js' import { ICryptoProvider, Logger } from '../../utils/index.js' +/** Current state of the transport */ export enum TransportState { /** * Transport has no active connections nor trying to connect to anything diff --git a/packages/core/src/storage/abstract.ts b/packages/core/src/storage/abstract.ts index 4a457c9b..b5ac2be5 100644 --- a/packages/core/src/storage/abstract.ts +++ b/packages/core/src/storage/abstract.ts @@ -6,24 +6,36 @@ import { Logger } from '../utils/index.js' // eslint-disable-next-line @typescript-eslint/no-namespace export namespace ITelegramStorage { + /** Information about a cached peer */ export interface PeerInfo { - // marked id + /** Peer marked ID */ id: number + /** Peer access hash */ accessHash: tl.Long + /** Peer type */ type: BasicPeerType + /** Peer username, if any */ username?: string + /** Peer phone number, if available */ phone?: string + /** Full TL object with the cached entity */ full: tl.TypeUser | tl.TypeChat } + /** Information about currently logged in user */ export interface SelfInfo { + /** Whether this is a bot */ isBot: boolean + /** Current user's ID */ userId: number } + /** Information about preferred DC-s for the user */ export interface DcOptions { + /** Main DC */ main: tl.RawDcOption + /** Media DC. Can be the same as main */ media: tl.RawDcOption } } diff --git a/packages/core/tsconfig.json b/packages/core/tsconfig.json index b840c259..d5f18899 100644 --- a/packages/core/tsconfig.json +++ b/packages/core/tsconfig.json @@ -13,19 +13,5 @@ "references": [ { "path": "../tl" }, { "path": "../tl-runtime" }, - ], - "typedocOptions": { - "name": "@mtcute/core", - "includeVersion": true, - "out": "../../docs/packages/core", - "validation": { - "notExported": true, - "invalidLink": true, - "notDocumented": false - }, - "excludePrivate": true, - "entryPoints": [ - "./src/index.ts" - ] - } + ] } diff --git a/packages/core/typedoc.cjs b/packages/core/typedoc.cjs new file mode 100644 index 00000000..29a85267 --- /dev/null +++ b/packages/core/typedoc.cjs @@ -0,0 +1,12 @@ +module.exports = { + extends: ['../../typedoc.base.cjs'], + entryPoints: [ + './src/index.ts', + './src/utils/index.ts', + './src/utils/crypto/node-crypto.ts', + './src/utils/crypto/subtle.ts', + './src/network/transports/tcp.ts', + './src/network/transports/websocket.ts', + ], + entryPointStrategy: 'expand', +} diff --git a/packages/core/typedoc.js b/packages/core/typedoc.js deleted file mode 100644 index 9b0b2805..00000000 --- a/packages/core/typedoc.js +++ /dev/null @@ -1,17 +0,0 @@ -const path = require('path') - -module.exports = { - ...require('../../typedoc.js'), - out: path.join( - __dirname, - '../../docs/packages/' + - require('./package.json').name.replace(/^@.+\//, ''), - ), - entryPoints: ['./src/index.ts'], - excludeExternals: true, - externalPattern: [ - // '../client/**/*', - '../tl/**/*', - '**/*/node_modules/**/*', - ], -} diff --git a/packages/crypto-node/typedoc.cjs b/packages/crypto-node/typedoc.cjs new file mode 100644 index 00000000..84e0d8c2 --- /dev/null +++ b/packages/crypto-node/typedoc.cjs @@ -0,0 +1,4 @@ +module.exports = { + extends: ['../../typedoc.base.cjs'], + entryPoints: ['./src/index.ts'], +} diff --git a/packages/crypto-node/typedoc.js b/packages/crypto-node/typedoc.js deleted file mode 100644 index 97451f42..00000000 --- a/packages/crypto-node/typedoc.js +++ /dev/null @@ -1,11 +0,0 @@ -const path = require('path') - -module.exports = { - ...require('../../typedoc.js'), - out: path.join( - __dirname, - '../../docs/packages/' + - require('./package.json').name.replace(/^@.+\//, ''), - ), - entryPoints: ['./src/index.ts'], -} diff --git a/packages/dispatcher/src/dispatcher.ts b/packages/dispatcher/src/dispatcher.ts index 0d35b515..ea27ef21 100644 --- a/packages/dispatcher/src/dispatcher.ts +++ b/packages/dispatcher/src/dispatcher.ts @@ -72,7 +72,7 @@ export interface DispatcherParams { /** * If this dispatcher can be used as a scene, its unique name. * - * Should not be set manually, use {@link Dispatcher#scene} instead + * Should not be set manually, use {@link Dispatcher.scene} instead */ sceneName?: string diff --git a/packages/dispatcher/typedoc.cjs b/packages/dispatcher/typedoc.cjs new file mode 100644 index 00000000..84e0d8c2 --- /dev/null +++ b/packages/dispatcher/typedoc.cjs @@ -0,0 +1,4 @@ +module.exports = { + extends: ['../../typedoc.base.cjs'], + entryPoints: ['./src/index.ts'], +} diff --git a/packages/dispatcher/typedoc.js b/packages/dispatcher/typedoc.js deleted file mode 100644 index 97451f42..00000000 --- a/packages/dispatcher/typedoc.js +++ /dev/null @@ -1,11 +0,0 @@ -const path = require('path') - -module.exports = { - ...require('../../typedoc.js'), - out: path.join( - __dirname, - '../../docs/packages/' + - require('./package.json').name.replace(/^@.+\//, ''), - ), - entryPoints: ['./src/index.ts'], -} diff --git a/packages/file-id/typedoc.cjs b/packages/file-id/typedoc.cjs new file mode 100644 index 00000000..84e0d8c2 --- /dev/null +++ b/packages/file-id/typedoc.cjs @@ -0,0 +1,4 @@ +module.exports = { + extends: ['../../typedoc.base.cjs'], + entryPoints: ['./src/index.ts'], +} diff --git a/packages/file-id/typedoc.js b/packages/file-id/typedoc.js deleted file mode 100644 index 97451f42..00000000 --- a/packages/file-id/typedoc.js +++ /dev/null @@ -1,11 +0,0 @@ -const path = require('path') - -module.exports = { - ...require('../../typedoc.js'), - out: path.join( - __dirname, - '../../docs/packages/' + - require('./package.json').name.replace(/^@.+\//, ''), - ), - entryPoints: ['./src/index.ts'], -} diff --git a/packages/html-parser/typedoc.cjs b/packages/html-parser/typedoc.cjs new file mode 100644 index 00000000..84e0d8c2 --- /dev/null +++ b/packages/html-parser/typedoc.cjs @@ -0,0 +1,4 @@ +module.exports = { + extends: ['../../typedoc.base.cjs'], + entryPoints: ['./src/index.ts'], +} diff --git a/packages/html-parser/typedoc.js b/packages/html-parser/typedoc.js deleted file mode 100644 index 97451f42..00000000 --- a/packages/html-parser/typedoc.js +++ /dev/null @@ -1,11 +0,0 @@ -const path = require('path') - -module.exports = { - ...require('../../typedoc.js'), - out: path.join( - __dirname, - '../../docs/packages/' + - require('./package.json').name.replace(/^@.+\//, ''), - ), - entryPoints: ['./src/index.ts'], -} diff --git a/packages/http-proxy/index.ts b/packages/http-proxy/index.ts index 67ad7a3d..bf991cdf 100644 --- a/packages/http-proxy/index.ts +++ b/packages/http-proxy/index.ts @@ -156,7 +156,7 @@ export abstract class BaseHttpProxyTcpTransport extends BaseTcpTransport { /** * HTTP(s) TCP transport using an intermediate packet codec. * - * Should be the one passed as `transport` to {@link TelegramClient} constructor + * Should be the one passed as `transport` to `TelegramClient` constructor * (unless you want to use a custom codec). */ export class HttpProxyTcpTransport extends BaseHttpProxyTcpTransport { diff --git a/packages/http-proxy/typedoc.cjs b/packages/http-proxy/typedoc.cjs new file mode 100644 index 00000000..a276ab05 --- /dev/null +++ b/packages/http-proxy/typedoc.cjs @@ -0,0 +1,4 @@ +module.exports = { + extends: ['../../typedoc.base.cjs'], + entryPoints: ['./index.ts'], +} diff --git a/packages/http-proxy/typedoc.js b/packages/http-proxy/typedoc.js deleted file mode 100644 index 6c152f90..00000000 --- a/packages/http-proxy/typedoc.js +++ /dev/null @@ -1,11 +0,0 @@ -const path = require('path') - -module.exports = { - ...require('../../typedoc.js'), - out: path.join( - __dirname, - '../../docs/packages/' + - require('./package.json').name.replace(/^@.+\//, ''), - ), - entryPoints: ['./index.ts'], -} diff --git a/packages/i18n/package.json b/packages/i18n/package.json index 99f47b55..d67b56ff 100644 --- a/packages/i18n/package.json +++ b/packages/i18n/package.json @@ -18,6 +18,10 @@ ".": { "import": "./esm/index.js", "require": "./cjs/index.js" + }, + "./plurals/*.js": { + "import": "./esm/plurals/*.js", + "require": "./cjs/plurals/*.js" } } }, diff --git a/packages/i18n/typedoc.cjs b/packages/i18n/typedoc.cjs new file mode 100644 index 00000000..5acba841 --- /dev/null +++ b/packages/i18n/typedoc.cjs @@ -0,0 +1,7 @@ +module.exports = { + extends: ['../../typedoc.base.cjs'], + entryPoints: [ + './src/index.ts', + './src/plurals/*.ts', + ], +} diff --git a/packages/i18n/typedoc.js b/packages/i18n/typedoc.js deleted file mode 100644 index f8c500ea..00000000 --- a/packages/i18n/typedoc.js +++ /dev/null @@ -1,15 +0,0 @@ -const path = require('path') - -module.exports = { - ...require('../../typedoc.js'), - out: path.join( - __dirname, - '../../docs/packages/' + - require('./package.json').name.replace(/^@.+\//, ''), - ), - entryPoints: [ - './src/index.ts', - './src/plurals/english.ts', - './src/plurals/russian.ts', - ], -} diff --git a/packages/markdown-parser/typedoc.cjs b/packages/markdown-parser/typedoc.cjs new file mode 100644 index 00000000..84e0d8c2 --- /dev/null +++ b/packages/markdown-parser/typedoc.cjs @@ -0,0 +1,4 @@ +module.exports = { + extends: ['../../typedoc.base.cjs'], + entryPoints: ['./src/index.ts'], +} diff --git a/packages/markdown-parser/typedoc.js b/packages/markdown-parser/typedoc.js deleted file mode 100644 index 97451f42..00000000 --- a/packages/markdown-parser/typedoc.js +++ /dev/null @@ -1,11 +0,0 @@ -const path = require('path') - -module.exports = { - ...require('../../typedoc.js'), - out: path.join( - __dirname, - '../../docs/packages/' + - require('./package.json').name.replace(/^@.+\//, ''), - ), - entryPoints: ['./src/index.ts'], -} diff --git a/packages/mtproxy/typedoc.cjs b/packages/mtproxy/typedoc.cjs new file mode 100644 index 00000000..a276ab05 --- /dev/null +++ b/packages/mtproxy/typedoc.cjs @@ -0,0 +1,4 @@ +module.exports = { + extends: ['../../typedoc.base.cjs'], + entryPoints: ['./index.ts'], +} diff --git a/packages/mtproxy/typedoc.js b/packages/mtproxy/typedoc.js deleted file mode 100644 index 6c152f90..00000000 --- a/packages/mtproxy/typedoc.js +++ /dev/null @@ -1,11 +0,0 @@ -const path = require('path') - -module.exports = { - ...require('../../typedoc.js'), - out: path.join( - __dirname, - '../../docs/packages/' + - require('./package.json').name.replace(/^@.+\//, ''), - ), - entryPoints: ['./index.ts'], -} diff --git a/packages/node/typedoc.cjs b/packages/node/typedoc.cjs new file mode 100644 index 00000000..803aef46 --- /dev/null +++ b/packages/node/typedoc.cjs @@ -0,0 +1,11 @@ +module.exports = { + extends: ['../../typedoc.base.cjs'], + entryPoints: ['./index.ts'], + externalPattern: [ + '../client/**', + '../core/**', + '../html-parser/**', + '../markdown-parser/**', + '../sqlite/**', + ], +} diff --git a/packages/node/typedoc.js b/packages/node/typedoc.js deleted file mode 100644 index fe075b8d..00000000 --- a/packages/node/typedoc.js +++ /dev/null @@ -1,22 +0,0 @@ -const path = require('path') - -module.exports = { - ...require('../../typedoc.js'), - out: path.join( - __dirname, - '../../docs/packages/' + - require('./package.json').name.replace(/^@.+\//, ''), - ), - entryPoints: ['./index.ts'], - excludeExternals: true, - externalPattern: [ - '../client/**/*', - '../dispatcher/**/*', - '../tl/**/*', - '../html-parser/**/*', - '../markdown-parser/**/*', - '../core/**/*', - '../sqlite/**/*', - '**/*/node_modules/**/*', - ], -} diff --git a/packages/socks-proxy/index.ts b/packages/socks-proxy/index.ts index e8833cf7..74f2ac13 100644 --- a/packages/socks-proxy/index.ts +++ b/packages/socks-proxy/index.ts @@ -413,7 +413,7 @@ export abstract class BaseSocksTcpTransport extends BaseTcpTransport { /** * Socks TCP transport using an intermediate packet codec. * - * Should be the one passed as `transport` to {@link TelegramClient} constructor + * Should be the one passed as `transport` to `TelegramClient` constructor * (unless you want to use a custom codec). */ export class SocksTcpTransport extends BaseSocksTcpTransport { diff --git a/packages/socks-proxy/typedoc.cjs b/packages/socks-proxy/typedoc.cjs new file mode 100644 index 00000000..a276ab05 --- /dev/null +++ b/packages/socks-proxy/typedoc.cjs @@ -0,0 +1,4 @@ +module.exports = { + extends: ['../../typedoc.base.cjs'], + entryPoints: ['./index.ts'], +} diff --git a/packages/socks-proxy/typedoc.js b/packages/socks-proxy/typedoc.js deleted file mode 100644 index 6c152f90..00000000 --- a/packages/socks-proxy/typedoc.js +++ /dev/null @@ -1,11 +0,0 @@ -const path = require('path') - -module.exports = { - ...require('../../typedoc.js'), - out: path.join( - __dirname, - '../../docs/packages/' + - require('./package.json').name.replace(/^@.+\//, ''), - ), - entryPoints: ['./index.ts'], -} diff --git a/packages/sqlite/typedoc.cjs b/packages/sqlite/typedoc.cjs new file mode 100644 index 00000000..a276ab05 --- /dev/null +++ b/packages/sqlite/typedoc.cjs @@ -0,0 +1,4 @@ +module.exports = { + extends: ['../../typedoc.base.cjs'], + entryPoints: ['./index.ts'], +} diff --git a/packages/sqlite/typedoc.js b/packages/sqlite/typedoc.js deleted file mode 100644 index 6c152f90..00000000 --- a/packages/sqlite/typedoc.js +++ /dev/null @@ -1,11 +0,0 @@ -const path = require('path') - -module.exports = { - ...require('../../typedoc.js'), - out: path.join( - __dirname, - '../../docs/packages/' + - require('./package.json').name.replace(/^@.+\//, ''), - ), - entryPoints: ['./index.ts'], -} diff --git a/packages/tl-runtime/typedoc.cjs b/packages/tl-runtime/typedoc.cjs new file mode 100644 index 00000000..52937666 --- /dev/null +++ b/packages/tl-runtime/typedoc.cjs @@ -0,0 +1,4 @@ +module.exports = { + extends: ['../../typedoc.base.cjs'], + entryPoints: ['./src'], +} diff --git a/packages/tl-runtime/typedoc.js b/packages/tl-runtime/typedoc.js deleted file mode 100644 index daa200c7..00000000 --- a/packages/tl-runtime/typedoc.js +++ /dev/null @@ -1,12 +0,0 @@ -const path = require('path') - -module.exports = { - ...require('../../typedoc.js'), - out: path.join( - __dirname, - '../../docs/packages/' + - require('./package.json').name.replace(/^@.+\//, ''), - ), - entryPoints: ['./src'], - entryPointStrategy: 'expand', -} diff --git a/packages/tl-utils/typedoc.cjs b/packages/tl-utils/typedoc.cjs new file mode 100644 index 00000000..84e0d8c2 --- /dev/null +++ b/packages/tl-utils/typedoc.cjs @@ -0,0 +1,4 @@ +module.exports = { + extends: ['../../typedoc.base.cjs'], + entryPoints: ['./src/index.ts'], +} diff --git a/packages/tl-utils/typedoc.js b/packages/tl-utils/typedoc.js deleted file mode 100644 index 97451f42..00000000 --- a/packages/tl-utils/typedoc.js +++ /dev/null @@ -1,11 +0,0 @@ -const path = require('path') - -module.exports = { - ...require('../../typedoc.js'), - out: path.join( - __dirname, - '../../docs/packages/' + - require('./package.json').name.replace(/^@.+\//, ''), - ), - entryPoints: ['./src/index.ts'], -} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index cad6f992..378913dd 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -309,7 +309,7 @@ importers: version: 5.2.3 ts-node: specifier: 10.9.1 - version: 10.9.1(@types/node@18.16.0)(typescript@5.0.4) + version: 10.9.1(@types/node@20.8.9)(typescript@5.2.2) devDependencies: '@mtcute/core': specifier: workspace:^1.0.0 @@ -982,6 +982,12 @@ packages: /@types/node@18.16.0: resolution: {integrity: sha512-BsAaKhB+7X+H4GnSjGhJG9Qi8Tw+inU9nJDwmD5CgOmBLEI6ArdhikpLX7DjbjDRDTbqZzU2LSQNZg8WGPiSZQ==} + /@types/node@20.8.9: + resolution: {integrity: sha512-UzykFsT3FhHb1h7yD4CA4YhBHq545JC0YnEz41xkipN88eKQtL6rSgocL5tbAP6Ola9Izm/Aw4Ora8He4x0BHg==} + dependencies: + undici-types: 5.26.5 + dev: false + /@types/normalize-package-data@2.4.1: resolution: {integrity: sha512-Gj7cI7z+98M282Tqmp2K5EIsoouUEzbBJhQQzDE3jSIRk6r9gsz0oUokqIUR4u1R3dMHo0pDHM7sNOHyhulypw==} dev: true @@ -1645,7 +1651,7 @@ packages: normalize-path: 3.0.0 readdirp: 3.6.0 optionalDependencies: - fsevents: 2.3.2 + fsevents: 2.3.3 dev: true /chownr@1.1.4: @@ -2705,8 +2711,8 @@ packages: /fs.realpath@1.0.0: resolution: {integrity: sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==} - /fsevents@2.3.2: - resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==} + /fsevents@2.3.3: + resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==} engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0} os: [darwin] requiresBuild: true @@ -5237,6 +5243,38 @@ packages: typescript: 5.0.4 v8-compile-cache-lib: 3.0.1 yn: 3.1.1 + dev: true + + /ts-node@10.9.1(@types/node@20.8.9)(typescript@5.2.2): + resolution: {integrity: sha512-NtVysVPkxxrwFGUUxGYhfux8k78pQB3JqYBXlLRZgdGUqTO5wU/UyHop5p70iEbGhB7q5KmiZiU0Y3KlJrScEw==} + hasBin: true + peerDependencies: + '@swc/core': '>=1.2.50' + '@swc/wasm': '>=1.2.50' + '@types/node': '*' + typescript: '>=2.7' + peerDependenciesMeta: + '@swc/core': + optional: true + '@swc/wasm': + optional: true + dependencies: + '@cspotcode/source-map-support': 0.8.1 + '@tsconfig/node10': 1.0.8 + '@tsconfig/node12': 1.0.9 + '@tsconfig/node14': 1.0.1 + '@tsconfig/node16': 1.0.2 + '@types/node': 20.8.9 + acorn: 8.10.0 + acorn-walk: 8.2.0 + arg: 4.1.3 + create-require: 1.1.1 + diff: 4.0.2 + make-error: 1.3.6 + typescript: 5.2.2 + v8-compile-cache-lib: 3.0.1 + yn: 3.1.1 + dev: false /tsconfig-paths@3.14.2: resolution: {integrity: sha512-o/9iXgCYc5L/JxCHPe3Hvh8Q/2xm5Z+p18PESBU6Ff33695QnCHBEjcytY2q19ua7Mbl/DavtBOLq+oG0RCL+g==} @@ -5333,12 +5371,12 @@ packages: resolution: {integrity: sha512-cW9T5W9xY37cc+jfEnaUvX91foxtHkza3Nw3wkoF4sSlKn0MONdkdEndig/qPBWXNkmplh3NzayQzCiHM4/hqw==} engines: {node: '>=12.20'} hasBin: true + dev: true /typescript@5.2.2: resolution: {integrity: sha512-mI4WrpHsbCIcwT9cF4FZvr80QUeKvsUsUvKDoR+X/7XHQH98xYD8YHZg7ANtz2GtZt/CBq2QJ0thkGJMHfqc1w==} engines: {node: '>=14.17'} hasBin: true - dev: true /uglify-js@3.17.4: resolution: {integrity: sha512-T9q82TJI9e/C1TAxYvfb16xO120tMVFZrGA3f9/P4424DNu6ypK103y0GPFVa17yotwSyZW5iYXgjYHkGrJW/g==} @@ -5357,6 +5395,10 @@ packages: which-boxed-primitive: 1.0.2 dev: true + /undici-types@5.26.5: + resolution: {integrity: sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==} + dev: false + /unique-filename@1.1.1: resolution: {integrity: sha512-Vmp0jIp2ln35UTXuryvjzkjGdRyf9b2lTXuSYUiPmzRcl3FDtYqAwOnTJkAngD9SWhnoJzDbTKwaOrZ+STtxNQ==} dependencies: diff --git a/scripts/typedoc-external-links.cjs b/scripts/typedoc-external-links.cjs new file mode 100644 index 00000000..feb58bc4 --- /dev/null +++ b/scripts/typedoc-external-links.cjs @@ -0,0 +1,67 @@ +function load(app) { + app.converter.addUnknownSymbolResolver((declaration) => { + const symbol = declaration.symbolReference?.path?.map((path) => path.path).join('.') + + if (symbol === 'Long' || symbol === 'tl.Long') { + return { + target: 'https://github.com/dcodeIO/long.js', + caption: symbol, + } + } + + if (symbol === 'BigInteger') { + return { + target: 'https://github.com/peterolson/BigInteger.js', + caption: symbol, + } + } + + if (symbol.startsWith('tl.')) { + let [ns, name] = symbol.slice(3).split('.') + + if (!name) { + name = ns + ns = null + } + + let kind + + if (name.startsWith('Type')) { + kind = 'union' + name = name.slice(4) + } else if (name.startsWith('Raw')) { + name = name[3].toLowerCase() + name.slice(4) + + if (name.endsWith('Method')) { + kind = 'method' + name = name.slice(0, -6) + } else { + kind = 'class' + } + } + + name = (ns ? ns + '.' : '') + name + + let url + + switch (kind) { + case 'union': + url = `https://core.telegram.org/type/${name}` + break + case 'method': + url = `https://core.telegram.org/method/${name}` + break + case 'class': + url = `https://core.telegram.org/constructor/${name}` + break + } + + return { + target: url, + caption: symbol, + } + } + }) +} + +module.exports = { load } diff --git a/typedoc.base.cjs b/typedoc.base.cjs new file mode 100644 index 00000000..92eb1c15 --- /dev/null +++ b/typedoc.base.cjs @@ -0,0 +1,19 @@ +module.exports = { + includeVersion: true, + validation: { + notExported: true, + invalidLink: false, + notDocumented: false, + }, + excludePrivate: true, + excludeExternals: true, + excludeInternal: true, + exclude: [ + '**/*/dist', + '**/*/node_modules', + './packages/tl/**/*', + ], + plugin: [ + './scripts/typedoc-external-links.cjs', + ], +} diff --git a/typedoc.cjs b/typedoc.cjs new file mode 100644 index 00000000..0d51e4b4 --- /dev/null +++ b/typedoc.cjs @@ -0,0 +1,14 @@ +const fs = require('fs') +const path = require('path') + +module.exports = { + ...require('./typedoc.base.cjs'), + name: 'mtcute', + out: './docs', + entryPoints: fs + .readdirSync(path.join(__dirname, 'packages')) + .filter((it) => !['crypto', 'tl', 'create-bot'].includes(it)) + .map((it) => `packages/${it}`), + entryPointStrategy: 'packages', + // logLevel: 'Verbose', +} diff --git a/typedoc.js b/typedoc.js deleted file mode 100644 index 29c8e189..00000000 --- a/typedoc.js +++ /dev/null @@ -1,16 +0,0 @@ -const path = require('path') - -module.exports = { - includeVersion: true, - validation: { - notExported: true, - invalidLink: true, - notDocumented: true, - }, - excludePrivate: true, - excludeExternals: true, - exclude: ['**/*/dist', '**/*/node_modules'], - plugin: [ - path.join(__dirname, 'scripts/totally-great-typedoc-plugin.js'), - ], -}