@citestyle/ris 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Proximify
+
+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,101 @@
+# @citestyle/ris
+
+RIS parser and serializer. Converts between RIS (Research Information Systems) tagged format and CSL-JSON, the standard input format for Citestyle.
+
+## Installation
+
+```bash
+npm install @citestyle/ris
+```
+
+## Usage
+
+### Parse RIS to CSL-JSON
+
+```js
+import { parseRis } from '@citestyle/ris'
+
+const ris = `
+TY  - JOUR
+AU  - Smith, John
+AU  - Doe, Jane
+TI  - A Study of Climate Change
+JF  - Nature Climate Change
+PY  - 2024
+VL  - 14
+SP  - 100
+EP  - 108
+DO  - 10.1038/example
+ER  -
+`
+
+const items = parseRis(ris)
+console.log(items[0].title)            // "A Study of Climate Change"
+console.log(items[0].author.length)    // 2
+console.log(items[0].page)             // "100-108"
+console.log(items[0].DOI)              // "10.1038/example"
+```
+
+### Export CSL-JSON to RIS
+
+```js
+import { exportRis } from '@citestyle/ris'
+
+const items = [{
+  id: '1',
+  type: 'article-journal',
+  title: 'A Study of Climate Change',
+  author: [
+    { family: 'Smith', given: 'John' },
+    { family: 'Doe', given: 'Jane' },
+  ],
+  issued: { 'date-parts': [[2024]] },
+  'container-title': 'Nature Climate Change',
+  volume: '14',
+  page: '100-108',
+  DOI: '10.1038/example',
+}]
+
+const output = exportRis(items)
+// TY  - JOUR
+// AU  - Smith, John
+// AU  - Doe, Jane
+// TI  - A Study of Climate Change
+// ...
+// ER  -
+```
+
+### Pipeline: RIS to formatted bibliography
+
+```js
+import { parseRis } from '@citestyle/ris'
+import { createRegistry } from '@citestyle/registry'
+import * as apa from '@citestyle/styles/apa'
+
+const ris = readFileSync('export.ris', 'utf-8')
+const items = parseRis(ris)
+
+const registry = createRegistry(apa)
+registry.addItems(items)
+
+const bibliography = registry.getBibliography()
+bibliography.forEach(entry => console.log(entry.html))
+```
+
+## API
+
+### `parseRis(str)`
+
+Parse a RIS string into an array of CSL-JSON items.
+
+**Features:**
+- 30+ RIS type codes (JOUR, BOOK, CHAP, THES, CONF, RPRT, etc.)
+- Repeatable tags (AU for multiple authors, KW for keywords)
+- SP + EP page merging into a single page range
+- Date parsing from PY and DA tags
+- Editor (A2/ED), translator, and other contributor roles
+- Common in exports from PubMed, Scopus, Web of Science, and Zotero
+
+### `exportRis(items)`
+
+Serialize an array of CSL-JSON items to a RIS string. Each item is delimited by `TY` (type) and `ER` (end of record) tags.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@citestyle/ris",
+  "version": "0.1.0",
+  "description": "RIS ↔ CSL-JSON parser and serializer",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "types.d.ts",
+    "README.md"
+  ],
+  "dependencies": {
+    "@citestyle/types": "0.0.2"
+  },
+  "devDependencies": {
+    "vitest": "^3.1.1"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run --passWithNoTests",
+    "lint": "echo 'TODO: configure linter'"
+  }
+}

package/src/export.js

@@ -0,0 +1,127 @@
+/**
+ * Serialize CSL-JSON items as a RIS string.
+ *
+ * @param {object[]} items - CSL-JSON items
+ * @returns {string} RIS source
+ */
+
+// ── CSL type → RIS type mapping ────────────────────────────────────────────
+
+const REVERSE_TYPE_MAP = {
+  'article-journal': 'JOUR',
+  'article-magazine': 'MGZN',
+  'article-newspaper': 'NEWS',
+  'article': 'GEN',
+  'book': 'BOOK',
+  'chapter': 'CHAP',
+  'dataset': 'DATA',
+  'graphic': 'ART',
+  'legal_case': 'CASE',
+  'legislation': 'STAT',
+  'manuscript': 'UNPB',
+  'map': 'MAP',
+  'motion_picture': 'MPCT',
+  'pamphlet': 'PAMP',
+  'paper-conference': 'CONF',
+  'patent': 'PAT',
+  'personal_communication': 'PCOMM',
+  'report': 'RPRT',
+  'software': 'COMP',
+  'song': 'MUSIC',
+  'thesis': 'THES',
+  'webpage': 'ELEC',
+}
+
+// ── Name serialization ──────────────────────────────────────────────────────
+
+function serializeName(name) {
+  if (name.literal) return name.literal
+  const parts = []
+  const particle = name['non-dropping-particle'] || name['dropping-particle'] || ''
+  const family = (particle ? particle + ' ' : '') + (name.family || '')
+  parts.push(family)
+  if (name.given) parts.push(name.given)
+  if (name.suffix) parts.push(name.suffix)
+  return parts.join(', ')
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+export function exportRis(items) {
+  if (!items || !items.length) return ''
+
+  return items.map(item => {
+    const lines = []
+    const tag = (t, v) => { if (v != null && v !== '') lines.push(`${t}  - ${v}`) }
+
+    // Type
+    tag('TY', REVERSE_TYPE_MAP[item.type] || 'GEN')
+
+    // ID
+    tag('ID', item.id)
+
+    // Authors
+    if (item.author) item.author.forEach(a => tag('AU', serializeName(a)))
+
+    // Editors
+    if (item.editor) item.editor.forEach(e => tag('A2', serializeName(e)))
+
+    // Title
+    tag('TI', item.title)
+
+    // Container title
+    if (item['container-title']) {
+      const ct = item.type === 'article-journal' ? 'JO' : 'T2'
+      tag(ct, item['container-title'])
+    }
+
+    // Abstract
+    tag('AB', item.abstract)
+
+    // Date
+    const dateParts = item.issued?.['date-parts']?.[0]
+    if (dateParts) {
+      const parts = [String(dateParts[0])]
+      if (dateParts[1]) parts.push(String(dateParts[1]).padStart(2, '0'))
+      if (dateParts[2]) parts.push(String(dateParts[2]).padStart(2, '0'))
+      tag('PY', parts.join('/'))
+    }
+
+    // Volume, issue
+    tag('VL', item.volume)
+    tag('IS', item.issue)
+
+    // Pages
+    if (item.page) {
+      const pageParts = item.page.split(/[–-]/)
+      tag('SP', pageParts[0].trim())
+      if (pageParts[1]) tag('EP', pageParts[1].trim())
+    }
+
+    // Identifiers and links
+    tag('DO', item.DOI)
+    tag('UR', item.URL)
+    tag('SN', item.ISSN || item.ISBN)
+
+    // Publisher
+    tag('PB', item.publisher)
+    tag('CY', item['publisher-place'])
+
+    // Other
+    tag('ET', item.edition)
+    tag('LA', item.language)
+    if (item['collection-title']) tag('T3', item['collection-title'])
+
+    // Keywords
+    if (item.keyword) {
+      item.keyword.split(/,\s*/).forEach(kw => tag('KW', kw.trim()))
+    }
+
+    // Notes
+    tag('N1', item.note)
+
+    // End record
+    lines.push('ER  - ')
+    return lines.join('\n')
+  }).join('\n') + '\n'
+}

package/src/index.js

@@ -0,0 +1,8 @@
+/**
+ * @citestyle/ris
+ *
+ * RIS ↔ CSL-JSON conversion.
+ */
+
+export { parseRis } from './parse.js'
+export { exportRis } from './export.js'

package/src/parse.js

@@ -0,0 +1,213 @@
+/**
+ * Parse a RIS string into an array of CSL-JSON items.
+ *
+ * RIS is a tagged format with TY (type) / ER (end) delimiters.
+ * Each tag is 2 uppercase letters followed by "  - " and a value.
+ * Common in database exports (PubMed, Scopus, Web of Science).
+ *
+ * @param {string} ris - RIS source
+ * @returns {object[]} Array of CSL-JSON items
+ */
+
+// ── RIS type → CSL type mapping ────────────────────────────────────────────
+
+const TYPE_MAP = {
+  ABST: 'article',
+  ADVS: 'motion_picture',
+  ART: 'graphic',
+  BILL: 'bill',
+  BOOK: 'book',
+  CASE: 'legal_case',
+  CHAP: 'chapter',
+  COMP: 'software',
+  CONF: 'paper-conference',
+  CTLG: 'book',
+  DATA: 'dataset',
+  EDBOOK: 'book',
+  EJOUR: 'article-journal',
+  ELEC: 'webpage',
+  GEN: 'article',
+  HEAR: 'legal_case',
+  ICOMM: 'personal_communication',
+  INPR: 'article-journal',
+  JOUR: 'article-journal',
+  JFULL: 'article-journal',
+  MAP: 'map',
+  MGZN: 'article-magazine',
+  MPCT: 'motion_picture',
+  MUSIC: 'song',
+  NEWS: 'article-newspaper',
+  PAMP: 'pamphlet',
+  PAT: 'patent',
+  PCOMM: 'personal_communication',
+  RPRT: 'report',
+  SER: 'article',
+  SLIDE: 'graphic',
+  SOUND: 'song',
+  STAND: 'legislation',
+  STAT: 'legislation',
+  THES: 'thesis',
+  UNPB: 'manuscript',
+  VIDEO: 'motion_picture',
+}
+
+// ── Name parsing ────────────────────────────────────────────────────────────
+
+function parseName(str) {
+  if (!str) return null
+  str = str.trim()
+
+  // "Last, First Suffix" or "Last, First, Suffix"
+  const parts = str.split(',').map(s => s.trim())
+  if (parts.length >= 2) {
+    const result = { family: parts[0] }
+    // Check if third part is a suffix
+    if (parts.length >= 3) {
+      result.given = parts[1]
+      result.suffix = parts[2]
+    } else {
+      result.given = parts[1]
+    }
+    return result
+  }
+
+  // Single name (corporate author)
+  return { literal: str }
+}
+
+// ── Date parsing ────────────────────────────────────────────────────────────
+
+function parseDate(str) {
+  if (!str) return null
+  str = str.trim()
+
+  // Common formats: YYYY, YYYY/MM/DD, YYYY/MM, YYYY/MM/DD/other
+  const parts = str.split('/')
+  const year = parseInt(parts[0], 10)
+  if (isNaN(year)) return null
+
+  const dateParts = [year]
+  if (parts[1]) {
+    const month = parseInt(parts[1], 10)
+    if (!isNaN(month) && month >= 1 && month <= 12) {
+      dateParts.push(month)
+      if (parts[2]) {
+        const day = parseInt(parts[2], 10)
+        if (!isNaN(day) && day >= 1 && day <= 31) dateParts.push(day)
+      }
+    }
+  }
+  return { 'date-parts': [dateParts] }
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+export function parseRis(ris) {
+  if (!ris || typeof ris !== 'string') return []
+
+  const items = []
+  let current = null
+
+  const lines = ris.split(/\r?\n/)
+
+  for (const line of lines) {
+    // RIS tag format: XX  - value (2 chars, 2 spaces, dash, space, value)
+    const match = line.match(/^([A-Z][A-Z0-9])\s{2}-\s?(.*)$/)
+    if (!match) continue
+
+    const [, tag, value] = match
+    const val = value.trim()
+
+    if (tag === 'TY') {
+      current = { type: TYPE_MAP[val] || 'article', _raw: {} }
+      continue
+    }
+
+    if (tag === 'ER') {
+      if (current) {
+        items.push(finalizeItem(current))
+        current = null
+      }
+      continue
+    }
+
+    if (!current) continue
+
+    // Accumulate tags (some are repeatable)
+    if (!current._raw[tag]) current._raw[tag] = []
+    current._raw[tag].push(val)
+  }
+
+  // Handle unterminated record
+  if (current) items.push(finalizeItem(current))
+
+  return items
+}
+
+function finalizeItem(record) {
+  const raw = record._raw
+  const item = { type: record.type }
+
+  // ID
+  item.id = first(raw.ID) || first(raw.AN) || `ris-${Date.now()}`
+
+  // Authors (AU/A1 are primary authors)
+  const authors = [...(raw.AU || []), ...(raw.A1 || [])]
+  if (authors.length) item.author = authors.map(parseName).filter(Boolean)
+
+  // Editors (A2/ED)
+  const editors = [...(raw.A2 || []), ...(raw.ED || [])]
+  if (editors.length) item.editor = editors.map(parseName).filter(Boolean)
+
+  // Title
+  item.title = first(raw.TI) || first(raw.T1) || ''
+
+  // Container title
+  const container = first(raw.T2) || first(raw.JO) || first(raw.JF) || first(raw.JA) || first(raw.J2)
+  if (container) item['container-title'] = container
+
+  // Abstract
+  const abstract = first(raw.AB) || first(raw.N2)
+  if (abstract) item.abstract = abstract
+
+  // Date
+  const dateStr = first(raw.PY) || first(raw.Y1) || first(raw.DA)
+  if (dateStr) {
+    const d = parseDate(dateStr)
+    if (d) item.issued = d
+  }
+
+  // Simple fields
+  if (first(raw.VL)) item.volume = first(raw.VL)
+  if (first(raw.IS)) item.issue = first(raw.IS)
+
+  // Pages: SP (start) + EP (end)
+  const sp = first(raw.SP)
+  const ep = first(raw.EP)
+  if (sp && ep) item.page = `${sp}–${ep}`
+  else if (sp) item.page = sp
+
+  if (first(raw.DO)) item.DOI = first(raw.DO)
+  if (first(raw.UR)) item.URL = first(raw.UR)
+  if (first(raw.SN)) item.ISSN = first(raw.SN)
+  if (first(raw.PB)) item.publisher = first(raw.PB)
+  if (first(raw.CY)) item['publisher-place'] = first(raw.CY)
+  if (first(raw.ET)) item.edition = first(raw.ET)
+  if (first(raw.LA)) item.language = first(raw.LA)
+
+  // Keywords (repeatable)
+  if (raw.KW && raw.KW.length) item.keyword = raw.KW.join(', ')
+
+  // Notes
+  const notes = [...(raw.N1 || []), ...(raw.RN || [])]
+  if (notes.length) item.note = notes.join('; ')
+
+  // Series
+  if (first(raw.T3)) item['collection-title'] = first(raw.T3)
+
+  return item
+}
+
+function first(arr) {
+  return arr && arr.length ? arr[0] : null
+}

package/types.d.ts

@@ -0,0 +1 @@
+export { parseRis, exportRis } from '@citestyle/types'