・コマンドライン スクリプトのテンプレート ・単一の.tsファイル ・サブコマンド対応 ・環境 deno 2.7.10 (stable, release, x86_64-pc-windows-msvc) v8 14.7.173.7-rusty typescript 5.9.2 ・ダウンロード#!/usr/bin/env -S deno run --allow-all /** * 汎用コマンドラインツールのテンプレート - cmdutils * * ### 提供コマンド: * - `renumber`: 指定したディレクトリ内の画像を連番で一括リネームする。 * * ### 使用例: * ```bash * deno run -A cmdutils.ts renumber --prefix "vacation_" --start 1 * ``` * * Deno 2.7.10 / TypeScript 準拠 * * @module */ import { parseArgs } from "jsr:@std/cli@^1.0.28/parse-args"; import * as path from "jsr:@std/path@^1.1.4"; import { exists } from "jsr:@std/fs@^1.0.23/exists"; const PROG_VERSION = "2026.04.04"; /** * コマンドのインターフェース */ interface BaseCommand { /** コマンド識別子 */ readonly name: string; /** ヘルプ画面に表示される説明文 */ readonly description: string; /** * ヘルプ情報を標準出力。 */ showHelp(): void; /** * コマンドのメインロジックを実行する。 * * @param args 解析前のコマンドライン引数 * @returns 終了コード（0: 成功、それ以外: 失敗） */ run(args: string[]): Promise<number>; } /** * オプション解析機能を持つサブコマンドのインターフェース * * 各サブコマンドごとに独自の引数を持つため、 * その解析ロジック(parseOptions)と戻り値の型をBaseCommandから分離。 * * @template T コマンド独自の解析済みオプション型 */ interface SubCommand<T> extends BaseCommand { /** * サブコマンド名を除いた引数リストを解析し、独自のオプション型を返す。 * * @param args サブコマンド以降の引数 */ parseOptions(args: string[]): T; } /** * `renumber` コマンドで使用するパース済みオプション */ interface ReNumberOptions { /** 出力ファイル名の先頭に付与する文字列 */ prefix: string; /** 連番の開始番号 */ startNo: number; /** リネーム実施フラグ(trueで実際にリネームをする) */ isFix: boolean; /** 最低桁数 */ minDigits: number; } interface FileInfo { fullPath: string; baseName: string; ext: string; } interface RenamePlan { file: FileInfo; newName: string; isNew: boolean; } /** * ディレクトリ内の画像ファイルを連番で一括リネームするコマンド */ export class ReNumberCommand implements SubCommand<ReNumberOptions> { readonly name = "renumber"; readonly description = "画像ファイルを連番でリネームします。"; /** * 処理対象とする拡張子のリスト。 * 全て小文字、ドット付きで定義。 */ private static readonly TARGET_EXTS: readonly string[] = [ ".jpg", ".png", ".webp", ".bmp", ".jpeg", ".gif" ]; /** * カレントディレクトリから対象ファイルを収集し、自然順でソートし取得する。 * * @returns ソート済みのファイル情報(FileInfo)の配列 * * @remarks * - 拡張子の判定は大文字小文字を区別しない。 * - ソートは「自然順（数値順）」かつ * 「大文字小文字・全角半角を区別する」設定で行う。 */ private async collectFiles(): Promise<FileInfo[]> { const files: FileInfo[] = []; for await (const entry of Deno.readDir(".")) { if (!entry.isFile) continue; const { name: basename, ext } = path.parse(entry.name); if (ReNumberCommand.TARGET_EXTS.includes(ext.toLowerCase())) { files.push({ fullPath: entry.name, ext: ext, baseName: basename, }); } } const collator = new Intl.Collator("ja", { numeric: true, sensitivity: "variant", }); files.sort((a, b) => collator.compare(a.baseName, b.baseName)); return files; } /** * 対象ファイル群に対して、新しいファイル名を含むリネーム計画を作成する。 * * @param targetFiles - リネーム対象となるファイルの情報の配列 * @param prefix - ファイル名の先頭に付与する文字列 * @param startNo - 連番の開始番号 * @param digits - 連番部分の最小桁数（足りない場合は `0` で埋められる） * @returns 各ファイルの新旧名と変更の有無を含む計画オブジェクトの配列 * * @remarks * - 実際のファイル名は元の拡張子の大小文字を維持する。 * - 変更の有無判定においては、ベース名は厳密に比較するが、 * 拡張子のみ大文字小文字の違いを無視して比較を行う。 * - 例：`Photo.JPG` から `Photo.jpg` への変更は「変更なし」と判定する。 */ private createRenamePlan( targetFiles: FileInfo[], prefix: string, startNo: number, digits: number ) { return targetFiles.map((file, index) => { const numPart = String(startNo + index).padStart(digits, "0"); const newName = `${prefix}${numPart}${file.ext}`; const isNew = file.fullPath !== newName; return { file, newName, isNew }; }); } /** * 作成されたリネーム計画に衝突や重複がないか、実行前に一括検証する。 * * @param renamePlan - 検証対象となるリネーム計画の配列 * @param allTargets - 今回のリネーム処理の全対象ファイル情報の配列 * @returns 計画が安全で実行可能な場合は true、衝突が検知された場合は false * * @remarks * 以下の 2 点をチェックし、データの安全性を担保する： * * 1. **リネーム予定名同士の重複**: * 計画内で複数のファイルが同じ名前になろうとしていないかを確認する。 * 判定は大文字小文字を区別せずに行う。 * * 2. **外部ファイルとの衝突**: * リネーム先のパスに既にファイルが存在する場合、それが「今回移動して場所を * 空ける予定のファイル」であるかを確認する。 * 今回の対象外である（居座り続ける）ファイルと衝突する場合は、上書き事故を * 防ぐため不許可とする。 */ private async validatePlan( renamePlan: RenamePlan[], allTargets: FileInfo[] ): Promise<boolean> { const usedNames = new Set<string>(); for (const plan of renamePlan) { if (!plan.isNew) continue; const newNorm = plan.newName.toLowerCase(); if (usedNames.has(newNorm)) { console.error( "中止: リネーム予定同士のファイル名が重複します: " + `${plan.newName}` ); return false; } usedNames.add(newNorm); if (await exists(plan.newName)) { const isWillBeMoved = allTargets.some(f => f.fullPath.toLowerCase() === plan.newName.toLowerCase() ); if (!isWillBeMoved) { console.error(`中止: 既存の別ファイルと衝突します: ${plan.newName}`); return false; } } } return true; } /** * リネーム計画に基づき、実際のファイル移動処理を実行する。 * * @param renamePlan - 作成されたリネーム計画の配列 * @param isFix - true の場合は実際にリネームを実行し、false の場合は表示のみ行う * @returns 全てのリネームが正常に完了した場合は true、途中で失敗した場合は false * * @remarks * - **玉突き衝突の回避**: `01.jpg -> 02.jpg`, `02.jpg -> 03.jpg` のような * 連鎖的なリネームを安全に行うため計画を逆順（配列の末尾）から処理すること * で、移動先のパスを常に空けた状態で実行する。 * - **エラーハンドリング**: いずれかのリネームに失敗した場合、ファイルシステ * ムの一貫性を守るためエラーを出力して即座に処理を中断し `false` を返す。 * - **スキップ判定**: 名前変更なし または シミュレーション の場合は * コンソール表示のみを行い、実際のリネーム処理はスキップする。 */ private async executeRename( renamePlan: RenamePlan[], isFix: boolean, ): Promise<boolean> { for (let i = renamePlan.length - 1; i >= 0; i--) { const { file, newName, isNew } = renamePlan[i]; const status = isNew ? "" : " (変更なし)"; console.log(`${file.fullPath} -> ${newName}${status}`); if (!isNew || !isFix) continue; try { await Deno.rename(file.fullPath, newName); } catch (error) { console.error( `FAILED: ${file.fullPath} のリネームに失敗しました:`, error ); return false; } } return true; } /** * ヘルプ情報を標準出力。 */ showHelp(): void { console.log(` Command: ${this.name} Description: ${this.description} Usage: deno run -A cmdutils.ts ${this.name} [options] Options: -e, --prefix <string> 出力ファイル名の接頭辞 (デフォルト: "") -n, --start <number> 開始番号 (デフォルト: 1) -d, --digits <number> 最低桁数 (デフォルト: 自動計算) --fix シミュレーションではなく実際にリネームを実行 -h, --help このヘルプを表示 FEATURES: - 自然順ソート: "file2.txt" が "file10.txt" より前に並びます。 CAUTION: - リネーム先に「対象外の同名ファイル」が存在する場合は 上書き防止のため処理を中断します。` ); } /** * 引数を `ReNumberOptions` 型にパースする。 * * @param rawArgs コマンドライン引数の配列 * @returns パース済みのオプションオブジェクト */ parseOptions(rawArgs: string[]): ReNumberOptions { const args = parseArgs(rawArgs, { string: ["e"], boolean: ["fix"], alias: { e: "prefix", n: "start", d: "digits", }, default: { e: "", n: 1, d: 0, // 0は自動計算を意味する fix: false, }, }); return { prefix: String(args.e), startNo: Number(args.n) || 1, minDigits: Number(args.d) || 0, isFix: Boolean(args.fix), }; } /** * コマンドのメインロジックを実行する。 * * @param rawArgs 引数配列 * @returns 終了コード (0: 成功, 1: 衝突による中止) * @throws {Error} ファイルシステム操作に失敗した場合 */ async run(rawArgs: string[]): Promise<number> { const { prefix, startNo, isFix, minDigits } = this.parseOptions(rawArgs); const targetFiles = await this.collectFiles(); if (targetFiles.length === 0) { console.log("対象となる画像ファイルが見つかりませんでした。"); return 0; } const autoDigits = String(targetFiles.length + startNo - 1).length; const digits = Math.max(autoDigits, minDigits); const renamePlan = this.createRenamePlan(targetFiles, prefix, startNo, digits); if (!await this.validatePlan(renamePlan, targetFiles)) { return 1; } await this.executeRename(renamePlan, isFix); if(!isFix) { console.log( "\n【シミュレーション】" + " 実際に変更するには --fix を指定してください" ); } return 0; } } /** * ツール全体のライフサイクルとコマンド実行を管理するメインクラス */ class Main { private commands: Map<string, BaseCommand> = new Map(); constructor() { this.registerCommand(...[ new ReNumberCommand(), // ----------------------------------------------------------- // TODO: **** ここにサブコマンドを追記していく **** // ----------------------------------------------------------- ]); } /** * コマンドを内部レジストリに登録する。 * * @param cmd 登録するコマンドインスタンス */ private registerCommand(cmd: BaseCommand): void { this.commands.set(cmd.name, cmd); } /** * ヘルプ情報を標準出力。 * * @returns 常に0（正常終了コード） */ private showHelp(): number { console.log( "Usage: deno run -A cmdUtils.ts [command] [options]" + "\nCommands:" ); for (const cmd of this.commands.values()) { console.log(` ${cmd.name.padEnd(15)} : ${cmd.description}`); } return 0; } /** * アプリケーションのメインエントリーポイント。 * * 引数を解析し、適切なサブコマンドを呼び出す。 * * @returns プロセスの終了コード */ async exec(): Promise<number> { const args = parseArgs(Deno.args, { stopEarly: true, // 最初の引数をサブコマンドとして扱う boolean: ["help", "version"], alias: { h: "help", v: "version" }, }); if (args.version) { console.log(`${PROG_VERSION}`); return 0; } const [subCommandName, ...remainingArgs] = args._.map(String); if (args.help || !subCommandName) { return this.showHelp(); } const command = this.commands.get(subCommandName); if (!command) { console.error(`Unknown command: ${subCommandName}`); return 1; } // サブコマンド固有のヘルプ (例: renumber --help) // remainingArgs の中に --help が含まれているかチェック const subArgs = parseArgs(remainingArgs, { boolean: ["help"], alias: { h: "help" }, }); if (remainingArgs.length === 0 || subArgs.help) { command.showHelp(); return 0; } try { const exitCode = await command.run(remainingArgs); return exitCode; } // 想定外のエラー（権限不足やディスクフルなど） catch (error) { console.error(`[Fatal Error] ${command.name}:`, error instanceof Error ? error.message : error); return 1; } } } /** * 直接実行された場合のみアプリケーションを起動 */ if (import.meta.main) { const exitCode = await new Main().exec(); Deno.exit(exitCode); }
[Deno/TypeScript] コマンドラインスクリプトのテンプレート（サブコマンド対応）
ラベル:
Deno,
TypeScript
[Deno] 開発環境構築 例 VSCode
１．インストール ・公式サイト https://deno.com/ ・Deno自体は単一ファイル 約128MB deno 2.7.9 (stable, release, x86_64-pc-windows-msvc) v8 14.7.173.7-rusty typescript 5.9.2 ・TypeScript/JavaScriptの開発ツール＋実行環境＋配布ツールというオールインワン ・Node.jsを作った人がNode.jsの設計ミスを悔やんで新しく作った # Denoのインストール(システムグローバル) ## Linux / macOS $ curl -fsSL https://deno.com/install.sh | sh ## Windows PowerShell $ iwr https://deno.com/install.ps1 -useb | iex # バージョン確認 $ deno --version # Deno自身にアップデートがあるか確認 $ deno upgrade --dry-run # deno自体を最新版にアップグレード $ deno upgrade # 指定したバージョンのDenoを取得する $ mkdir bin $ deno upgrade --version 2.5.6 --output .\bin\deno-2.5.6.exe ※Deno自体は単一の実行可能ファイルなので余計なパスを生成しないzipファイルをDLしてもよい。 https://github.com/denoland/deno/releases ※複数バージョンを利用したい場合は環境切り替えツールを使うか、実行可能ファイルをリネームして使う(deno2.1.exe deno2.2.exeなど) ※キャッシュ(外部ライブラリ)自体はバージョン毎に保持されている。 ※2024年以降、外部ライブラリは https://deno.land/x/ ではなく JSR (jsr:) を使うのが標準。 ２．実行 deno.json のタスクを使う（推奨） deno.json に以下のように記述しプロジェクト内のDenoを意識せず実行する。$ deno task dev # システムグローバルのDenoから起動する $ ./bin/deno task dev # プロジェクト内のDenoから起動する ※tasksではプロジェクト内のDenoを使う記述なのでどちらで起動しても同じ ※deno task (引数なし) を実行すると deno.json に登録されているタスク名と実行内容の一覧が表示される。 ３．VSCodeで使う方法 ・プロジェクトディレクト内で完結する持ち運び可能な構成 ・Deno自体を格納する(./bin/deno.exe) ・プロジェクトで使う実行時に必要なDeno関連の追加モジュール(./vendor or ./node_modules) ☆必須拡張機能 Deno (公式) 拡張機能 ID: denoland.vscode-deno 提供元: denoland (Deno公式チーム) 役割: 型チェック、補完、フォーマット（整形）、リント（構文チェック）、デバッグ、テスト実行など、Deno開発に必要なすべての機能が含まれている。 初期化 SHIFT+CTRL+P で Deno: Initialize Workspace Configuration ３．１．設定ファイルの書き方 プロジェクトディレクトリ配下 .vscode/settings.json{ // プロジェクト内にライブラリを実体化し、オフライン/持ち運びを可能にする "nodeModulesDir": "auto", "vendor": true, "tasks": { "check-update": "./bin/deno.exe outdated", "update": "./bin/deno.exe outdated --update", "backup": "./bin/deno.exe run --allow-read --allow-write --allow-run scripts/backup.ts", "backup": "./bin/deno.exe run --allow-all scripts/backup.ts", "build": "deno run --allow-all scripts/build.ts", "dev": "./bin/deno.exe run --allow-all --watch main.ts", "release": "./bin/deno.exe run --allow-write --allow-run scripts/build.ts ./main.ts myprog", "dev-2_5_6": "./bin/deno-2.5.6.exe run --allow-all --watch main.ts", "release-2_5_6": "./bin/deno-2.5.6.exe run --allow-write --allow-run scripts/build.ts ./main.ts myprog2.5" } }・settings.json の "deno.path" は単一のパスしか保持できない。 ・エディタの補完(IntelliSense)に使うDeno本体を切り替えたい場合は deno.path を手動で書き換える必要がある。 ３．２．推奨されるディレクトリ構成の例 my-project/ ├── .vscode/ │ ├── settings.json VS Code拡張機能・ターミナルの設定 │ └── launch.json F5デバッグの設定 ├── vendor/ 【自動生成】ここにライブラリの実体が展開される ├── node_modules/ 【自動生成】ここにライブラリの実体が展開される ├── bin/ │ └── deno.exe 特定バージョンのDeno本体 ├── scripts/ │ ├── build.ts リリース物生成 │ └── backup.ts 全体バックアップ ├── dist/ 【自動生成】リリース用生成物 ├── src/ ソースコード階層 │ ├── auth/ │ │ ├── mod.ts パッケージの玄関口 │ │ └── login.ts 内部ロジック │ └── utils/ 共通ユーティリティ │ ├── mod.ts パッケージの玄関口 │ └── logger.ts 内部ロジック ├── .gitignore git非対象パスの指定 ├── deno.json プロジェクト設定・タスク定義 ├── deno.lock 【自動生成】依存関係のバージョン固定ファイル └── main.ts エントリーポイント ３．３．インポートは相対パスで main.ts から auth パッケージを呼び出す場合は以下のように書く。{ "deno.enable": true, "deno.lint": true, "deno.cacheOnSave": true, "deno.path": "./bin/deno.exe", "terminal.integrated.env.windows": { "PATH": "${workspaceFolder}\\bin;${env:PATH}" } }３．４．mod.ts という慣習 Deno(およびRustなど)の世界では、ディレクトリ内の機能を外部に公開するファイル名を mod.ts とするのが一般的。Pythonの __init__.py と同じ役割で、そのディレクトリ内の「玄関口」になる。 ３．５．deno.json でのパス解決（インポートマップ） 階層が深くなって ./../../ と書くのが面倒な場合は deno.json にエイリアス(別名)を設定する。import { login } from "./src/auth/mod.ts";こうすると、どこからでも import { authenticate } from "@auth"; で呼び出せるようになり、Pythonのパッケージインポートに近い感覚になる。 ※外部モジュールは手動書き換えではなく、ターミナルで $ deno add jsr:@std/path と打つ。 これにより、最新の安定版が deno.json に自動登録されスペルミスやバージョン不整合を防げる。 ３．６．gitを使う場合 この構成をGitで管理する場合は vendor/ と node_modules/ は絶対に .gitignore に入れる。 理由: キャッシュにはダウンロードされた膨大な外部ライブラリが含まれるため、Gitのリポジトリが巨大化する。 推奨される .gitignore{ "tasks": { ... }, // ここの詳細は上記を参照 "imports": { // 外部ライブラリ "@deno-library/compress": "jsr:@deno-library/compress@^0.5.6", "@std/datetime": "jsr:@std/datetime@^0.225.7", "@std/path": "jsr:@std/path@^1.1.4", // 内部パッケージ "@auth": "./src/auth/mod.ts" } }４．実装のイメージ ４．１．内部ロジック (src/auth/login.ts)vendor/ node_modules/ dist/４．２．玄関口 (src/auth/mod.ts) Pythonの from .login import authenticate に相当するexport function authenticate(user: string): string { return `${user} は認証されました`; }４．３．利用側(main.ts) インポートマップで定義したエイリアス、または mod.ts を直接指定して機能を呼び出す。// 内部の必要な機能だけを選んで再エクスポート（Re-export）する export { authenticate } from "./login.ts";４．４．Denoならではのポイント 明示的な指定: Denoでは ./src/auth のようにディレクトリ名で止めることはできず、必ず mod.ts などのファイル名と .ts 拡張子まで書くのが基本ルール。 カプセル化: login.ts に関数が多数あっても、mod.ts で export しない限り外部からは見えない。これによりパッケージの独立性を保てる。 ５．デバッグ ５．１．F5でデバックするための設定 プロジェクトディレクトリ配下 .vscode/launch.jsonimport { authenticate } from "@auth"; console.log(authenticate("Deno太郎"));設定のポイント １．runtimeExecutable: ここにプロジェクト内の deno.exe をフルパス（変数を活用）で指定することで、システムのDenoではなく「そのプロジェクト専用のDeno」でデバッグが走る。 ２．--inspect-wait: デバッガーが接続されるまでプログラムの実行を待機させるフラグ。これにより、最初の1行目からステップ実行が可能になる。 ６．リリース 単一.tsファイルならそのままでもOK。 Windows以外の環境ならShebang（#!/usr/bin/env deno）が有効なので .ts ファイルで直接実行可能。 複数ファイル構造ならWindows環境を含めた配布を考えるなら deno compile によるバイナリ化が最適。 ６．１．scripts/build.ts 実行可能モジュールとしてリリースする場合はコンパル用のバッチプログラムを作っておく。 ※Deno 2.x の compile は、npm: インポートを含むプロジェクトも単一バイナリに固めることができる。{ "version": "0.2.0", "configurations": [ { "request": "launch", "name": "Launch Program", "type": "node", "program": "${workspaceFolder}/main.ts", "cwd": "${workspaceFolder}", "env": {}, "runtimeExecutable": "${workspaceFolder}/bin/deno.exe", "runtimeArgs": [ "run", "--unstable", "--inspect-wait", "--allow-all" ], "attachSimplePort": 9229 } ] }７．プロジェクトのバックアップ (scripts/backup.ts) プロジェクト全体をZIPにまとめ、親ディレクトリへ退避させるスクリプト。 ※実行には最新の std/archive モジュールを利用する想定。 ７．１．scripts/backup.ts の実装import * as datetime from "@std/datetime"; import * as path from "@std/path"; // 1. 保存先ディレクトリの作成 const distDir = "./dist"; await Deno.mkdir(distDir, { recursive: true }); // 2. タイムスタンプ生成 (YYYYMMDD_hhmmss) const now = new Date(); const timestamp = datetime.format(now, "yyyyMMdd_HHmmss"); // 3. 出力パスの組み立て const extension = Deno.build.os === "windows" ? ".exe" : ""; const outputName = `myapp_v${timestamp}${extension}`; const outputPath = path.join(distDir, outputName); console.log(`Building to: ${outputPath}...`); // 4. コンパイル実行 const command = new Deno.Command(Deno.execPath(), { args: [ "compile", "--allow-all", "--output", outputPath, "main.ts" ], }); const { success, stderr } = await command.output(); if(success) { console.log(`Successfully created: ${outputPath}`); } else { console.error("Compile failed:"); console.error(new TextDecoder().decode(stderr)); }/** * 使い方: * deno task build* 例: deno task build src/main.ts my-app */ import * as datetime from "@std/datetime"; import * as path from "@std/path"; const [entryPoint, binName] = Deno.args; if(!entryPoint || !binName) { console.error("Usage: deno task build "); console.error("example: deno task build src/main.ts my-app"); Deno.exit(1); } // 1. 保存先ディレクトリの作成 const distDir = "./dist"; await Deno.mkdir(distDir, { recursive: true }); // 2. タイムスタンプ生成 (YYYYMMDD_hhmmss) const now = new Date(); const timestamp = datetime.format(now, "yyyyMMdd_HHmmss"); // 3. 出力パスの組み立て const extension = Deno.build.os === "windows" ? ".exe" : ""; const outputName = `${binName}_v${timestamp}${extension}`; const outputPath = path.join(distDir, outputName); console.log(`Building to: ${outputPath}...`); // 4. コンパイル実行 const command = new Deno.Command(Deno.execPath(), { args: [ "compile", "--allow-all", "--output", outputPath, entryPoint ], }); const { success, stderr } = await command.output(); if(success) { console.log(`Successfully created: ${outputPath}`); } else { console.error("Compile failed:"); console.error(new TextDecoder().decode(stderr)); }
ラベル:
Deno,
JavaScript,
TypeScript
登録:
コメント (Atom)