폴더 구조를 모듈식으로 직접 매핑하기 위한 CLI 도구 생성

제목에는 지금 전달할 뜻이 하나도 없는 것 같지만 도해라면 다음과 같은 도구다.

|-src
  |-assets
    |- font
      |- aldrich.ttf
    |- image
      |- player.png
      |- enemy.png

이 구조의 폴더를 대상으로 하면...

import mod_0 from "./font/aldrich.ttf";
import mod_1 from "./image/player.png";
import mod_2 from "./image/enemy.png";
export default {
  "font": {
    "aldrich": mod_0
  },
  "image": {
    "player": mod_1,
    "enemy": mod_2
  }
};

상기 내용의 파일을 생성src/assets/index.js.

상세한 개요

피나였구나.js의 개발에서 자산 파일을 추가, 삭제할 때마다 코드 주체를 수정하는데 이것은 번거로움을 해결하기 위해 만든 도구이다.
다만, 특별히 의존하는 포장이 아니기 때문에 피나.js와 전혀 무관한 사용 방법도 가능합니다.
하나의 예로 생성된 모듈은phina이다.js에 사용된 예를 쓰겠습니다.
방금 보여준 디렉터리 구조와 같이 폴더 이름font과 image이 피나의 자산 캐리어에 대응하는 형식이면 출력 모듈은 아무것도 하지 않고 초기화 처리를 응용하는 데 사용됩니다.

// src/index.js
import assetMap from "./assets/index";

// アプリケーション作成時にアセットをロード
const app = phina.game.GameApp({
  asset: assetMap,
  /* その他のオプション */
});

app.run();

도구 이름은 dimic입니다.
모방 디렉터리 (directory) 의 조합부터 시작합니다.
github 창고

사용법

전제 조건

이 도구를 사용하려면 미리 node를 사용해야 합니다.js v10.10 이상 설치해야 합니다.
npm의 버전은 도구와 무관하며, 다음 설명은 npx 명령을 사용하여 가져온 버전 (v5.2 이상) 을 전제로 합니다.
위에서 말한 바와 같이 기본적으로 파일src/assets/index.js이 출력됩니다. 같은 이름의 파일이 이미 있으면 덮어쓰지 않도록 주의하십시오.

설치 및 실행

설치 숙지npm install dimic전역 설치를 수행하려면 -g 옵션을 추가합니다.
그리고 프로젝트 폴더의 src/assets 아래에 이전의 예와 같이 적당한 폴더 파일이 있는 상태에서 다음 명령을 실행합니다.

npx dimic

(글로벌 설치 시 필요 없음npx처리가 시작된 지 얼마 되지 않아 src/assets/index.js라는 파일을 생성하면 OK입니다.

옵션

일반적인 CLI 도구와 마찬가지로 옵션을 추가하여 다양한 동작을 변경할 수 있습니다.다음은 주요 옵션입니다.
(이하 샘플 코드 생략npx

입력 출력 폴더, 파일 변경

dimic --input-dir static/assets --output-file index.ts

기본적으로 src/assets/는 입력 대상 디렉터리이고 출력 파일의 이름은 index.js이지만 상기 옵션을 지정하여 변경할 수 있습니다.
옵션 이름은 각각 생략할 수 있습니다-i, -o.

파일 감시(watch 옵션)

dimic --watch

감시 대상 디렉터리, 변경이 있으면 모듈 파일을 업데이트합니다.
생략해서 쓸 수도 있다-w.
그나저나 내부용은 chokidar입니다.

목록 개체 파일 필터링

대상 파일을 glob 형식으로 선별할 수 있습니다.

dimic --match *

기본값!_*(밑줄) 시작된 파일 이외의 모든 것이 대상이다. 즉, _player.png 이런 파일과 폴더가 무시되는 설정이다.
위에서 말한 바와 같이 *만 설정하면 모든 파일이 목록의 대상이 됩니다.
패턴이 일치하기 때문에 미니머치를 사용했기 때문에 아래의 블러셔 테이블을 참고할 수 있는 방법을 지정하고 싶습니다.
https://motemen.hatenablog.com/entry/2014/07/15/minimatch-cheat-sheet

출력 형식 변경

--format 옵션을 사용하여 출력 형식을 변경할 수 있습니다.

dimic --format json

상기 명령을 사용하여 json 형식으로 파일을 출력합니다.
현재 옵션은 esm(기본값), json 및 none입니다.esm는 시작 샘플에서 보듯이 none는 다음과 같은 간단한 export default 옵션입니다.

export default {
  "font": {
    "aldrich": "./font/aldrich.ttf"
  }
  "image": {
    "player": "./image/player.png",
    "enemy": "./image/enemy.png"
  }
}

다른 옵션도 있지만 상기 내용을 먼저 기억하면 충분하다고 생각합니다.

기타

개체 파일은 한 레이어로 제한됩니다.예컨대

src/assets/image/foo/bar.png처럼 한 단계 깊이의 레벨

src/assets/bar.png처럼 Tier 0에 있는 파일

무시됩니다.(이건 규격이 바뀔 수 있나요?)

적용:Type Script의 유형 정의 및 enum화 정보

이걸 읽는 당신이 타입 스크립트 사용자라면 관련 함수를 더 쉽게 사용할 수 있도록 자산의 유형을 정의하려고 할 수도 있습니다.
자산의 유형 정의는 keyof typeof 문법으로 실현할 수 있다.

// src/example.ts
import assetMap from "./assets/index";

type ImageKey = keyof typeof assetMap.image;
function createImg(key: ImageKey) {
  const img = document.createElement("img");
  img.src = assetMap.image[key];
  return img;
}

// VS Codeなら引数指定のときにインテリセンスが効くようになったり、
// 存在しないアセットキーを指定するとエラーを出してくれるようになります。
const img1 = createImg("player");
const img2 = createImg("palyer"); // エラー！

약간의 열광문자열 기반 열거 유형(문자열 Enum)적인 방법도 함께 소개한다.

import assetMap from "./assets/index";

/**
 * 指定オブジェクトのキーから文字列enumを作成するutil関数
 */
function objectKeysToEnum<
  T extends Record<string | number, any>
>(o: T): { [K in keyof T]: K } {
  return Object.keys(o).reduce((accumulator, currentValue) => {
    accumulator[currentValue] = currentValue;
    return accumulator;
  }, Object.create(null));
}

const ImageKey = objectKeysToEnum(assetMap.image)
console.log(ImageKey.player); // "player"
console.log(ImageKey.enemy); // "enemy"

// 型定義
type ImageKey = keyof typeof ImageKey;

기분 따위

node.js CLI 도구 최초 제작

제작 과정에서 "이미 비슷한 도구가 있는 것 같은데(바퀴의 재발명인가요?)이런 우려도 있었지만 CLI 도구 제작은 이전부터 해보고 싶었던 과제로 좋은 소재라 개의치 않는다

옵션명을 정하기가 좀 주저하다.웹 패키지, 롤러업 등 대형 도구를 참고하여 이름을 짓도록 하세요.

fs-mock은 fs-mock의 fs 관련 테스트를 했지만 이것도 좀 힘들다. 다음에 글을 쓰고 싶다

참고 자료

How to build a CLI with Node.js

pheanut :phina.js로 싸인 프레임?제대로 사용해보진 못했지만 스크립트에 자산을 조립하는 기능이 있는 것 같아서 이번에는 도구의 제안 힌트를 소개해 드리겠습니다.