refactor: improve parse claim types

Author: EdJoPaTo

scripts/compare_datatypes.ts

@@ -1,11 +1,10 @@
 #!/usr/bin/env ts-node
 import { kebabCase } from 'lodash-es'
 import { red, green } from 'tiny-chalk'
-import { parsers } from '../src/helpers/parse_claim.js'
+import { DataTypes } from '../src/types/claim.js'
+import { isOfType } from '../src/utils/utils.js'
 import { readJsonFile } from '../tests/lib/utils.js'
 
-const supportedTypes = Object.keys(parsers)
-
 const allDatatypes = readJsonFile('/tmp/all_wikidata_datatypes.json') as string[]
 allDatatypes
 .map(typeUri => {
@@ -15,7 +14,7 @@ allDatatypes
   return kebabCase(typeName)
 })
 .forEach(type => {
-  if (supportedTypes.includes(type)) {
+  if (isOfType(DataTypes, type)) {
     console.log(green('ok'), type)
   } else {
     console.error(red('unsupported type'), type)

src/helpers/parse_claim.ts

@@ -1,31 +1,43 @@
-import { convertTime } from './wikibase_time.js'
-import type { SimplifySnakOptions } from '../types/simplify_claims.js'
+import { convertTime, type TimeConverter, type TimeConverterFn } from './wikibase_time.js'
+import type { DataType } from '../types/claim.js'
+import type { SnakEntityValue, SnakGlobeCoordinateValue, SnakMonolingualTextValue, SnakQuantityValue, SnakStringValue, SnakTimeValue, SnakValue } from '../types/snakvalue.js'
 
-const simple = datavalue => datavalue.value
+const simple = <T>(datavalue: { readonly value: T }): T => datavalue.value
 
-const monolingualtext = (datavalue, options) => {
+const monolingualtext = (datavalue: SnakMonolingualTextValue, options: { readonly keepRichValues?: boolean } = {}) => {
   return options.keepRichValues ? datavalue.value : datavalue.value.text
 }
 
-const entity = (datavalue, options) => prefixedId(datavalue, options.entityPrefix)
+interface SimplifyEntitySnakOptions {
+  readonly entityPrefix?: string
+}
+
+const entity = (datavalue: SnakEntityValue, options: SimplifyEntitySnakOptions = {}) => prefixedId(datavalue, options.entityPrefix)
 
 const entityLetter = {
   item: 'Q',
   lexeme: 'L',
   property: 'P',
 } as const
 
-const prefixedId = (datavalue, prefix) => {
+const prefixedId = (datavalue: SnakEntityValue, prefix: string | undefined) => {
   const { value } = datavalue
-  const id = value.id || entityLetter[value['entity-type']] + value['numeric-id']
+  const id = 'id' in value ? value.id : (entityLetter[value['entity-type']] + value['numeric-id'])
   return typeof prefix === 'string' ? `${prefix}:${id}` : id
 }
 
-const quantity = (datavalue, options) => {
+interface SimplifiedQuantity {
+  amount: number
+  unit: string
+  upperBound?: number
+  lowerBound?: number
+}
+
+const quantity = (datavalue: SnakQuantityValue, options: { readonly keepRichValues?: boolean } = {}) => {
   const { value } = datavalue
   const amount = parseFloat(value.amount)
   if (options.keepRichValues) {
-    const richValue: any = {
+    const richValue: SimplifiedQuantity = {
       amount: parseFloat(value.amount),
       // ex: http://www.wikidata.org/entity/
       unit: value.unit.replace(/^https?:\/\/.*\/entity\//, ''),
@@ -38,59 +50,93 @@ const quantity = (datavalue, options) => {
   }
 }
 
-const coordinate = (datavalue, options) => {
+const coordinate = (datavalue: SnakGlobeCoordinateValue, options: { readonly keepRichValues?: boolean } = {}) => {
   if (options.keepRichValues) {
     return datavalue.value
   } else {
     return [ datavalue.value.latitude, datavalue.value.longitude ]
   }
 }
 
-const time = (datavalue, options: SimplifySnakOptions) => {
+interface SimplifyTimeSnakOptions {
+  readonly keepRichValues?: boolean
+  readonly timeConverter?: TimeConverterFn | TimeConverter
+}
+const time = (datavalue: SnakTimeValue, options: SimplifyTimeSnakOptions = {}) => {
   const timeValue = convertTime(options.timeConverter, datavalue.value)
   if (options.keepRichValues) {
-    const { timezone, before, after, precision, calendarmodel } = datavalue.value
-    return { time: timeValue, timezone, before, after, precision, calendarmodel }
+    return { ...datavalue.value, time: timeValue }
   } else {
     return timeValue
   }
 }
 
-export const parsers = {
-  commonsMedia: simple,
-  'external-id': simple,
-  'geo-shape': simple,
-  'globe-coordinate': coordinate,
-  math: simple,
-  monolingualtext,
-  'musical-notation': simple,
-  quantity,
-  string: simple,
-  'tabular-data': simple,
-  time,
-  url: simple,
-  'wikibase-entityid': entity,
-  'wikibase-form': entity,
-  'wikibase-item': entity,
-  'wikibase-lexeme': entity,
-  'wikibase-property': entity,
-  'wikibase-sense': entity,
-} as const
+type SimplifySnakOptions = SimplifyTimeSnakOptions & SimplifyEntitySnakOptions
 
-export function parseClaim (datatype, datavalue, options, claimId) {
+export function parseClaim (
+  datatype: DataType | undefined,
+  datavalue: SnakValue,
+  options: SimplifySnakOptions,
+  claimId: string,
+) {
   // Known case of missing datatype: form.claims, sense.claims
-  datatype = datatype || datavalue.type
-  // Known case requiring this: legacy "muscial notation" datatype
-  datatype = datatype.replace(' ', '-')
-
-  try {
-    return parsers[datatype](datavalue, options)
-  } catch (err: unknown) {
-    if (err instanceof Error && err.message === 'parsers[datatype] is not a function') {
-      err.message = `${datatype} claim parser isn't implemented
-      Claim id: ${claimId}
-      Please report to https://github.com/maxlath/wikibase-sdk/issues`
-    }
-    throw err
+  // datavalue.type is used then
+
+  // @ts-expect-error known case requiring this: legacy "musical notation" datatype
+  datatype = datatype?.replace(' ', '-')
+
+  if (
+    datatype === 'wikibase-form' ||
+    datatype === 'wikibase-item' ||
+    datatype === 'wikibase-lexeme' ||
+    datatype === 'wikibase-property' ||
+    datatype === 'wikibase-sense' ||
+    datavalue.type === 'wikibase-entityid'
+  ) {
+    return entity(datavalue as SnakEntityValue, options)
+  }
+
+  if (datatype === 'globe-coordinate' || datavalue.type === 'globecoordinate') {
+    return coordinate(datavalue as SnakGlobeCoordinateValue, options)
   }
+
+  if (datatype === 'monolingualtext' || datavalue.type === 'monolingualtext') {
+    return monolingualtext(datavalue as SnakMonolingualTextValue, options)
+  }
+
+  if (datatype === 'quantity' || datavalue.type === 'quantity') {
+    return quantity(datavalue as SnakQuantityValue, options)
+  }
+
+  if (datatype === 'time' || datavalue.type === 'time') {
+    return time(datavalue as SnakTimeValue, options)
+  }
+
+  if (
+    datatype === 'commonsMedia' ||
+    datatype === 'external-id' ||
+    datatype === 'geo-shape' ||
+    datatype === 'math' ||
+    datatype === 'musical-notation' ||
+    datatype === 'string' ||
+    datatype === 'tabular-data' ||
+    datatype === 'url' ||
+    datavalue.type === 'string'
+  ) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+    return simple(datavalue as SnakStringValue)
+  }
+
+  unknownClaimType(datatype, datavalue, claimId)
+}
+
+// TypeScript notices when the argument isnt `never` and does not compile in that case -> some case is not implemented
+function unknownClaimType (
+  datatype: never,
+  datavalue: { readonly type: never },
+  claimId: string,
+): never {
+  const minimal = String(datatype) || String(datavalue)
+  const full = JSON.stringify({ datatype, datavalue })
+  throw new Error(`${minimal} claim parser isn't implemented\nPlease report to https://github.com/maxlath/wikibase-sdk/issues\n\nClaim id: ${claimId}\n${full}`)
 }

src/helpers/simplify_claims.ts

@@ -1,14 +1,15 @@
 import { uniq } from '../utils/utils.js'
 import { parseClaim } from './parse_claim.js'
 import { truthyPropertyClaims, nonDeprecatedPropertyClaims } from './rank.js'
-import type { Claim, Claims, PropertyClaims, PropertyQualifiers, Qualifier, Qualifiers, Reference } from '../types/claim.js'
+import type { Claim, Claims, DataType, PropertyClaims, PropertyQualifiers, QualifierSnak, Qualifiers, Reference, ReferenceSnak, SnakType } from '../types/claim.js'
+import type { PropertyId } from '../types/entity.js'
 import type { SimplifiedClaim, SimplifiedClaims, SimplifiedPropertyClaims, SimplifySnakOptions, SimplifySnaksOptions } from '../types/simplify_claims.js'
+import type { SnakValue } from '../types/snakvalue.js'
 
-function simplifySnaks (snaks, options) {
+function simplifySnaks (snaks: Record<PropertyId, any[]>, options: SimplifySnaksOptions) {
   const { propertyPrefix } = options
   const simplifiedSnaks: any = {}
-  for (let id in snaks) {
-    const propertySnaks = snaks[id]
+  for (let [ id, propertySnaks ] of Object.entries(snaks)) {
     if (propertyPrefix) {
       id = propertyPrefix + ':' + id
     }
@@ -17,7 +18,7 @@ function simplifySnaks (snaks, options) {
   return simplifiedSnaks
 }
 
-function simplifyPropertySnaks (propertySnaks, options) {
+function simplifyPropertySnaks (propertySnaks: any[], options: SimplifySnaksOptions) {
   // Avoid to throw on empty inputs to allow to simplify claims array
   // without having to know if the entity as claims for this property
   // Ex: simplifyPropertyClaims(entity.claims.P124211616)
@@ -31,35 +32,40 @@ function simplifyPropertySnaks (propertySnaks, options) {
     propertySnaks = truthyPropertyClaims(propertySnaks)
   }
 
-  propertySnaks = propertySnaks
+  const simplified = propertySnaks
     .map(claim => simplifyClaim(claim, options))
     // Filter-out novalue and somevalue claims,
     // unless a novalueValue or a somevalueValue is passed in options
     // Considers null as defined
     .filter(obj => obj !== undefined)
 
   // Deduplicate values unless we return a rich value object
-  if (propertySnaks[0] && typeof propertySnaks[0] !== 'object') {
-    return uniq(propertySnaks)
+  if (simplified[0] && typeof simplified[0] !== 'object') {
+    return uniq(simplified)
   } else {
-    return propertySnaks
+    return simplified
   }
 }
 
-// Expects a single snak object
-// Ex: entity.claims.P369[0]
-function simplifySnak (claim, options) {
+/**
+ * tries to replace wikidata deep claim object by a simple value
+ * e.g. a string, an entity Qid or an epoch time number
+ *
+ * Expects a single snak object
+ * Ex: entity.claims.P369[0]
+ */
+function simplifySnak (claim: Claim | QualifierSnak | ReferenceSnak, options: SimplifySnakOptions) {
   const { keepQualifiers, keepReferences, keepIds, keepHashes, keepTypes, keepSnaktypes, keepRanks } = parseKeepOptions(options)
 
-  // tries to replace wikidata deep claim object by a simple value
-  // e.g. a string, an entity Qid or an epoch time number
-  const { mainsnak, rank } = claim
-
-  let value, datatype, datavalue, snaktype, isQualifierSnak, isReferenceSnak
-  if (mainsnak) {
-    datatype = mainsnak.datatype
-    datavalue = mainsnak.datavalue
-    snaktype = mainsnak.snaktype
+  let datatype: DataType | undefined
+  let datavalue: SnakValue
+  let snaktype: SnakType
+  let isQualifierSnak: boolean
+  let isReferenceSnak: boolean
+  if ('mainsnak' in claim) {
+    datatype = claim.mainsnak.datatype
+    datavalue = claim.mainsnak.datavalue
+    snaktype = claim.mainsnak.snaktype
   } else {
     // Qualifiers have no mainsnak, and define datatype, datavalue on claim
     datavalue = claim.datavalue
@@ -70,6 +76,7 @@ function simplifySnak (claim, options) {
     else isReferenceSnak = true
   }
 
+  let value: any
   if (datavalue) {
     value = parseClaim(datatype, datavalue, options, claim.id)
   } else {
@@ -84,7 +91,7 @@ function simplifySnak (claim, options) {
 
     const valueObj: any = { value }
 
-    if (keepHashes) valueObj.hash = claim.hash
+    if (keepHashes && 'hash' in claim) valueObj.hash = claim.hash
     if (keepTypes) valueObj.type = datatype
     if (keepSnaktypes) valueObj.snaktype = snaktype
 
@@ -109,18 +116,16 @@ function simplifySnak (claim, options) {
 
   if (keepSnaktypes) valueObj.snaktype = snaktype
 
-  if (keepRanks) valueObj.rank = rank
+  if (keepRanks && 'rank' in claim) valueObj.rank = claim.rank
 
-  const subSnaksOptions = getSubSnakOptions(options)
-  subSnaksOptions.keepHashes = keepHashes
+  const subSnaksOptions = { ...options, areSubSnaks: true }
 
   if (keepQualifiers) {
-    valueObj.qualifiers = simplifyQualifiers(claim.qualifiers, subSnaksOptions)
+    valueObj.qualifiers = 'qualifiers' in claim ? simplifyQualifiers(claim.qualifiers, subSnaksOptions) : {}
   }
 
   if (keepReferences) {
-    claim.references = claim.references || []
-    valueObj.references = simplifyReferences(claim.references, subSnaksOptions)
+    valueObj.references = 'references' in claim ? simplifyReferences(claim.references, subSnaksOptions) : []
   }
 
   if (keepIds) valueObj.id = claim.id
@@ -139,38 +144,42 @@ export function simplifyClaim (claim: Claim, options: SimplifySnakOptions = {}):
 }
 
 export function simplifyQualifiers (qualifiers: Qualifiers, options: SimplifySnaksOptions = {}) {
-  return simplifySnaks(qualifiers, getSubSnakOptions(options))
+  return simplifySnaks(qualifiers, { ...options, areSubSnaks: true })
 }
 export function simplifyPropertyQualifiers (propertyQualifiers: PropertyQualifiers, options: SimplifySnaksOptions = {}) {
-  return simplifyPropertySnaks(propertyQualifiers, getSubSnakOptions(options))
+  return simplifyPropertySnaks(propertyQualifiers, { ...options, areSubSnaks: true })
 }
-export function simplifyQualifier (qualifier: Qualifier, options: SimplifySnakOptions = {}) {
+export function simplifyQualifier (qualifier: QualifierSnak, options: SimplifySnakOptions = {}) {
   return simplifySnak(qualifier, options)
 }
 
-export function simplifyReferences (references: Reference[], options) {
+export function simplifyReferences (references: Reference[], options: SimplifySnaksOptions) {
   return references.map(refRecord => simplifyReferenceRecord(refRecord, options))
 }
-export function simplifyReferenceRecord (refRecord, options) {
-  const subSnaksOptions = getSubSnakOptions(options)
+export function simplifyReferenceRecord (refRecord: Reference, options: SimplifySnaksOptions) {
+  const subSnaksOptions = { ...options, areSubSnaks: true }
   const snaks = simplifySnaks(refRecord.snaks, subSnaksOptions)
   if (subSnaksOptions.keepHashes) return { snaks, hash: refRecord.hash }
   else return snaks
 }
 
-const getSubSnakOptions = (options: any = {}) => {
-  if (options.areSubSnaks) return options
-  // Using a new object so that the original options object isn't modified
-  else return Object.assign({}, options, { areSubSnaks: true })
-}
-
-const keepOptions = [ 'keepQualifiers', 'keepReferences', 'keepIds', 'keepHashes', 'keepTypes', 'keepSnaktypes', 'keepRanks', 'keepRichValues' ]
-
-const parseKeepOptions = options => {
+const keepOptions = [
+  'keepHashes',
+  'keepIds',
+  'keepQualifiers',
+  'keepRanks',
+  'keepReferences',
+  'keepRichValues',
+  'keepSnaktypes',
+  'keepTypes',
+] as const
+type KeepOption = typeof keepOptions[number]
+
+const parseKeepOptions = (options: SimplifySnakOptions): Record<KeepOption, boolean> => {
   if (options.keepAll) {
     keepOptions.forEach(optionName => {
-      if (options[optionName] == null) options[optionName] = true
+      options[optionName] = options[optionName] ?? true
     })
   }
-  return options
+  return options as Record<KeepOption, boolean>
 }