ddex-json-codec 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kazhs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# ddex-json-codec
+
+DDEX ERN規格のXML/JSON相互変換ライブラリ（TypeScript）
+
+## 特徴
+
+- ERN XMLからTypeScript型付きオブジェクトへの変換、およびその逆変換
+- ERN 3.8系 / 4系に対応（4系は未実装）
+- バージョン自動検出
+- [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser) ベース
+- Node.js >= 20
+
+## インストール
+
+```bash
+npm install ddex-json-codec
+# or
+pnpm add ddex-json-codec
+```
+
+## 使い方
+
+### XML → JSON
+
+```typescript
+import { xmlToJson } from 'ddex-json-codec';
+
+const message = xmlToJson(xmlString);
+console.log(message.ernVersion); // "3.8.1"
+console.log(message.resourceList); // SoundRecording[]
+```
+
+### JSON → XML
+
+```typescript
+import { jsonToXml } from 'ddex-json-codec';
+
+const xml = jsonToXml(message);
+// バージョン指定も可
+const xml382 = jsonToXml(message, '3.8.2');
+```
+
+### バージョン検出
+
+```typescript
+import { detectVersion } from 'ddex-json-codec';
+
+const version = detectVersion(xmlString); // "3.8.1"
+```
+
+## 対応バージョン
+
+| ERN バージョン | 状態 |
+|---|---|
+| 3.8 | 実装済み |
+| 3.8.1 | 実装済み |
+| 3.8.2 | 実装済み |
+| 3.8.3 | 実装済み |
+| 4.1 | 未実装 |
+| 4.1.1 | 未実装 |
+| 4.2 | 未実装 |
+| 4.3 | 未実装 |
+| 4.3.1 | 未実装 |
+| 4.3.2 | 未実装 |
+
+## API リファレンス
+
+### `xmlToJson(xml: string): DdexMessage`
+
+ERN XMLを解析し、型付きオブジェクトを返す。バージョンは自動検出される。
+
+### `jsonToXml(message: DdexMessage, version?: ErnVersion): string`
+
+`DdexMessage` をERN XMLに変換する。`version` 省略時は `message.ernVersion` を使用。
+
+### `detectVersion(xml: string): ErnVersion`
+
+ERN XMLのnamespace URIからバージョンを検出して返す。
+
+### 型
+
+```typescript
+interface DdexMessage {
+  ernVersion: ErnVersion;
+  messageHeader: MessageHeader;
+  updateIndicator?: string;
+  resourceList: SoundRecording[];
+  releaseList: Release[];
+  dealList: ReleaseDeal[];
+  partyList?: Party[];              // 4系のみ
+  trackReleaseList?: TrackRelease[]; // 4系のみ
+}
+```
+
+エクスポートされる型一覧:
+
+`DdexMessage`, `ErnVersion`, `ErnMajorVersion`, `MessageHeader`, `MessageParty`,
+`SoundRecording`, `Release`, `TrackRelease`, `ResourceGroup`, `ReleaseResourceReference`,
+`ReleaseDeal`, `Deal`, `DealTerms`, `Usage`,
+`Party`, `Artist`, `DisplayArtist`, `ResourceContributor`, `IndirectResourceContributor`,
+`TextWithAttribute`, `Genre`, `PLine`, `CLine`, `Title`
+
+## ライセンス
+
+[MIT](./LICENSE.md)

package/dist/index.d.mts

@@ -0,0 +1,290 @@
+//#region src/types/common.d.ts
+/**
+ * XML要素が属性とテキストを両方持つ場合の汎用型
+ *
+ * 例: <TitleText languageAndScriptCode="en">Some Song</TitleText>
+ * →  { value: "Some Song", languageAndScriptCode: "en" }
+ */
+type TextWithAttribute<T extends Record<string, string> = Record<string, never>> = {
+  value: string;
+} & T;
+interface Title {
+  titleText: string;
+  subTitle?: string;
+  titleType?: string;
+}
+interface PLine {
+  year?: string;
+  pLineText: string;
+}
+interface CLine {
+  year?: string;
+  cLineText: string;
+}
+interface Genre {
+  genreText: string;
+  subGenre?: string;
+}
+/** 4系: DisplayTitle（territory+lang属性付き） */
+interface DisplayTitle {
+  titleText: string;
+  subTitle?: string;
+  applicableTerritoryCode?: string;
+  languageAndScriptCode?: string;
+  isDefault?: boolean;
+}
+//#endregion
+//#region src/types/party.d.ts
+interface Party {
+  partyReference: string;
+  partyId?: string[];
+  partyName?: PartyName[];
+}
+interface PartyName {
+  fullName: string;
+  fullNameIndexed?: string;
+  languageAndScriptCode?: string;
+}
+interface Artist {
+  /** 解決済みの名前（3.8系: FullNameから直接取得、4系: PartyListから解決） */
+  name: string;
+  /** 4系のみ: 元の参照ID（ラウンドトリップ用） */
+  partyReference?: string;
+  partyId?: string[];
+  roles?: string[];
+}
+interface DisplayArtist {
+  artist: Artist;
+  sequenceNumber?: number;
+}
+interface ResourceContributor {
+  name: string;
+  role: string;
+  sequenceNumber?: number;
+  /** UserDefined時の属性 */
+  roleNamespace?: string;
+  roleUserDefinedValue?: string;
+}
+interface IndirectResourceContributor {
+  name: string;
+  role: string;
+  sequenceNumber?: number;
+}
+/** 4系: PartyReference参照のContributor */
+interface Contributor {
+  contributorPartyReference: string;
+  /** PartyList解決後に埋める */
+  name?: string;
+  role: string;
+  sequenceNumber?: number;
+}
+//#endregion
+//#region src/types/sound-recording.d.ts
+interface SoundRecording {
+  resourceReference: string;
+  type?: string;
+  soundRecordingId?: SoundRecordingId;
+  referenceTitle?: ReferenceTitle$1;
+  displayArtists: DisplayArtist[];
+  duration?: string;
+  creationDate?: string;
+  languageOfPerformance?: string;
+  pLine?: PLine;
+  /** 3.8系: territory別の詳細 */
+  detailsByTerritory?: SoundRecordingDetailsByTerritory[];
+  /** 4系: フラットなタイトルテキスト */
+  displayTitleText?: string;
+  /** 4系: 複数のDisplayTitle（territory+lang属性） */
+  displayTitles?: DisplayTitle[];
+  /** 4系: PartyReference参照のContributor */
+  contributors?: Contributor[];
+}
+interface SoundRecordingId {
+  isrc?: string;
+  catalogNumber?: string;
+}
+interface ReferenceTitle$1 {
+  titleText: string;
+  subTitle?: string;
+}
+interface SoundRecordingDetailsByTerritory {
+  territoryCode: string[];
+  displayArtists?: DisplayArtist[];
+  titles?: Title[];
+  labelName?: string;
+  pLine?: PLine;
+  genre?: Genre;
+  parentalWarningType?: string;
+  sequenceNumber?: number;
+  resourceContributors?: ResourceContributor[];
+  indirectResourceContributors?: IndirectResourceContributor[];
+}
+//#endregion
+//#region src/types/release.d.ts
+interface Release {
+  releaseReference: string;
+  releaseType?: string;
+  releaseId?: ReleaseId;
+  referenceTitle?: ReferenceTitle;
+  displayArtists: DisplayArtist[];
+  releaseResourceReferences?: ReleaseResourceReference[];
+  resourceGroup?: ResourceGroup;
+  duration?: string;
+  pLine?: PLine;
+  cLine?: CLine;
+  /** 3.8系: territory別の詳細 */
+  detailsByTerritory?: ReleaseDetailsByTerritory[];
+  /** 4系: フラットなタイトルテキスト */
+  displayTitleText?: string;
+  /** 4系: 複数のDisplayTitle（territory+lang属性） */
+  displayTitles?: DisplayTitle[];
+  /** 4系: ReleaseLabelReference（PartyRef値） */
+  releaseLabelReferences?: string[];
+  genre?: Genre;
+  parentalWarningType?: string;
+}
+interface ReferenceTitle {
+  titleText: string;
+  subTitle?: string;
+}
+interface ReleaseId {
+  icpn?: string;
+  isEan?: boolean;
+  isrc?: string;
+  gridOrIcpn?: string;
+  catalogNumber?: string;
+  proprietaryId?: string;
+}
+interface ReleaseResourceReference {
+  value: string;
+  releaseResourceType?: string;
+}
+interface ResourceGroup {
+  sequenceNumber?: number;
+  title?: string;
+  resourceGroups?: ResourceGroup[];
+  resourceGroupContentItems?: ResourceGroupContentItem[];
+}
+interface ResourceGroupContentItem {
+  sequenceNumber?: number;
+  resourceType?: string;
+  releaseResourceReference: ReleaseResourceReference;
+}
+interface TrackRelease {
+  releaseReference: string;
+  releaseId?: ReleaseId;
+  referenceTitle?: ReferenceTitle;
+  displayArtists?: DisplayArtist[];
+  releaseResourceReference: string;
+  /** 4系: 複数のDisplayTitle */
+  displayTitles?: DisplayTitle[];
+  /** 4系: ReleaseLabelReference */
+  releaseLabelReferences?: string[];
+  genre?: Genre;
+}
+interface ReleaseDetailsByTerritory {
+  territoryCode: string[];
+  displayArtists?: DisplayArtist[];
+  displayArtistName?: string;
+  titles?: Title[];
+  labelName?: string;
+  genre?: Genre;
+  parentalWarningType?: string;
+  originalReleaseDate?: string;
+  resourceGroup?: ResourceGroup;
+}
+//#endregion
+//#region src/types/deal.d.ts
+interface ReleaseDeal {
+  dealReleaseReferences: string[];
+  deals: Deal[];
+  effectiveDate?: string;
+}
+interface Deal {
+  dealReference?: string;
+  dealTerms: DealTerms;
+}
+interface DealTerms {
+  commercialModelType?: string;
+  /** 3.8系: Usage > UseType[] */
+  usage?: Usage;
+  /** 4系: UseType[] 直下 */
+  useTypes?: string[];
+  territoryCode?: string[];
+  validityPeriod?: ValidityPeriod;
+  priceInformation?: PriceInformation;
+  takeDown?: boolean;
+}
+interface Usage {
+  useTypes: string[];
+}
+interface ValidityPeriod {
+  startDate?: string;
+  endDate?: string;
+}
+interface PriceInformation {
+  priceType?: string;
+  wholesalePricePerUnit?: number;
+}
+//#endregion
+//#region src/types/ern.d.ts
+/**
+ * パッチレベルまでのバージョン（namespace URIから検出）
+ */
+type ErnVersion = '3.8' | '3.8.1' | '3.8.2' | '3.8.3' | '4.1' | '4.1.1' | '4.2' | '4.3' | '4.3.1' | '4.3.2';
+/**
+ * 変換ロジックの分岐用（メジャー系統のみ）
+ */
+type ErnMajorVersion = '3.8' | '4';
+interface MessageParty {
+  partyId?: string;
+  partyIdIsDpid?: boolean;
+  fullName?: string;
+  tradingName?: string;
+}
+interface MessageHeader {
+  messageThreadId?: string;
+  messageId: string;
+  messageFileName?: string;
+  messageSender: MessageParty;
+  messageRecipient: MessageParty;
+  messageCreatedDateTime: string;
+}
+interface DdexMessage {
+  ernVersion: ErnVersion;
+  messageHeader: MessageHeader;
+  updateIndicator?: string;
+  resourceList: SoundRecording[];
+  releaseList: Release[];
+  dealList: ReleaseDeal[];
+  /** 4系のみ: PartyList（ラウンドトリップ用に保持） */
+  partyList?: Party[];
+  /** 4系のみ: TrackRelease */
+  trackReleaseList?: TrackRelease[];
+}
+//#endregion
+//#region src/converter/xml-to-json/index.d.ts
+/**
+ * XML文字列をDdexMessageに変換する
+ */
+declare function xmlToJson(xml: string): DdexMessage;
+//#endregion
+//#region src/converter/json-to-xml/index.d.ts
+/**
+ * DdexMessageをXML文字列に変換する
+ */
+declare function jsonToXml(message: DdexMessage, version?: ErnVersion): string;
+//#endregion
+//#region src/version/detect.d.ts
+/**
+ * XMLの先頭部分からERNバージョンを検出する
+ *
+ * 検出戦略（Ruby実装 sshaw/ddex を参考）:
+ * 1. namespace URI から検出（4系、3.8系共通）
+ * 2. MessageSchemaVersionId 属性から検出（3.8系のフォールバック）
+ *
+ * 巨大ファイル対策として先頭1024バイトのみ読む
+ */
+declare function detectVersion(xml: string): ErnVersion;
+//#endregion
+export { type Artist, type CLine, type Contributor, type DdexMessage, type Deal, type DealTerms, type DisplayArtist, type DisplayTitle, type ErnMajorVersion, type ErnVersion, type Genre, type IndirectResourceContributor, type MessageHeader, type MessageParty, type PLine, type Party, type Release, type ReleaseDeal, type ReleaseResourceReference, type ResourceContributor, type ResourceGroup, type SoundRecording, type TextWithAttribute, type Title, type TrackRelease, type Usage, detectVersion, jsonToXml, xmlToJson };