@wemush/wols 0.1.0 → 1.3.0

package/dist/cjs/specimen.js

@@ -3,15 +3,31 @@
  * Specimen Creation and Serialization
  *
  * This module provides functions to create and serialize
- * WOLS v1.1.0 compliant specimen objects.
+ * WOLS v1.3.0 compliant specimen objects.
  *
  * @module specimen
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRIMORDIA_AS_TYPE_WARNING = void 0;
 exports.createSpecimen = createSpecimen;
 exports.serializeSpecimen = serializeSpecimen;
 const types_js_1 = require("./types.js");
 const cuid_js_1 = require("./utils/cuid.js");
+const iso8601_js_1 = require("./utils/iso8601.js");
+/**
+ * Warning code emitted when `PRIMORDIA` is supplied as a specimen type.
+ *
+ * @since 1.3.0
+ */
+exports.PRIMORDIA_AS_TYPE_WARNING = 'PRIMORDIA_AS_TYPE';
+function primordiaWarning() {
+    return {
+        path: 'type',
+        code: exports.PRIMORDIA_AS_TYPE_WARNING,
+        message: `'PRIMORDIA' is a growth stage, not a specimen type; resolved to type 'FRUITING'`,
+        suggestion: `Use type: 'FRUITING', stage: 'PRIMORDIA'`,
+    };
+}
 /**
  * Expand a strain input to a full Strain object.
  * String inputs are expanded to { name: string }.
@@ -34,11 +50,17 @@ function expandStrain(strain) {
 /**
  * Create a new specimen with auto-generated ID and JSON-LD fields.
  *
- * This function creates a fully-formed WOLS v1.1.0 compliant Specimen
+ * This function creates a fully-formed WOLS v1.3.0 compliant Specimen
  * with automatic ID generation, version assignment, and JSON-LD context.
  *
+ * Type aliases resolve case-insensitively. `PRIMORDIA` supplied as a type
+ * resolves to `FRUITING`, sets `stage: 'PRIMORDIA'` when no stage was given
+ * (a supplied stage is never overridden), and emits a warning.
+ *
  * @param input - Specimen creation parameters
+ * @param options - `onWarning` receives non-fatal warnings (default: console.warn)
  * @returns Fully-formed Specimen with JSON-LD fields
+ * @throws Error if the type is unknown or `created` is not ISO 8601
  *
  * @example
  * ```typescript
@@ -68,26 +90,74 @@ function expandStrain(strain) {
  *   species: 'Ganoderma lucidum',
  *   strain: 'Reishi Red',  // Auto-expands to { name: 'Reishi Red' }
  * });
+ *
+ * // PRIMORDIA as a type (v1.3.0) -> type FRUITING, stage PRIMORDIA, plus a warning
+ * const pinning = createSpecimen(
+ *   { type: 'PRIMORDIA', species: 'Pleurotus ostreatus' },
+ *   { onWarning: w => console.info(w.message) }
+ * );
+ *
+ * // Explicit creation timestamp (v1.3.0)
+ * const dated = createSpecimen({
+ *   type: 'CULTURE',
+ *   species: 'Pleurotus ostreatus',
+ *   created: '2025-12-16T10:30:00Z',
+ * });
  * ```
  */
-function createSpecimen(input) {
+function createSpecimen(input, options = {}) {
     const id = (0, types_js_1.asSpecimenId)((0, cuid_js_1.createSpecimenId)());
     const strain = expandStrain(input.strain);
+    // Resolve type alias to canonical WOLS type (e.g., 'LIQUID_CULTURE' -> 'CULTURE')
+    const resolved = (0, types_js_1.resolveTypeAndStage)(input.type, input.stage);
+    if (resolved === null) {
+        throw new Error(`Invalid specimen type: '${input.type}'. ` +
+            `Must be one of: CULTURE, SPAWN, SUBSTRATE, FRUITING, HARVEST ` +
+            `(or a registered alias).`);
+    }
+    let created;
+    if (input.created !== undefined) {
+        if (input.created instanceof Date) {
+            if (Number.isNaN(input.created.getTime())) {
+                throw new Error('Invalid created timestamp: Date is invalid. Must be ISO 8601.');
+            }
+            created = input.created.toISOString();
+        }
+        else {
+            created = input.created;
+        }
+        if (typeof created !== 'string' || !(0, iso8601_js_1.isValidISO8601)(created)) {
+            throw new Error(`Invalid created timestamp: '${String(input.created)}'. Must be ISO 8601.`);
+        }
+    }
+    if (resolved.primordia) {
+        const warning = primordiaWarning();
+        if (options.onWarning) {
+            options.onWarning(warning);
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.warn(`[@wemush/wols] ${warning.message}. ${warning.suggestion ?? ''}`.trim());
+        }
+    }
     // Build specimen with required fields
     const specimen = {
         '@context': types_js_1.WOLS_CONTEXT,
         '@type': 'Specimen',
         id,
         version: types_js_1.WOLS_VERSION,
-        type: input.type,
+        type: resolved.type,
         species: input.species,
     };
     // Add optional fields only if defined
     if (strain !== undefined) {
         specimen.strain = strain;
     }
-    if (input.stage !== undefined) {
-        specimen.stage = input.stage;
+    if (resolved.stage !== undefined) {
+        specimen.stage = resolved.stage;
+    }
+    if (created !== undefined) {
+        specimen.created = created;
     }
     if (input.batch !== undefined) {
         specimen.batch = input.batch;
@@ -101,6 +171,9 @@ function createSpecimen(input) {
     if (input.custom !== undefined) {
         specimen.custom = input.custom;
     }
+    if (input._meta !== undefined) {
+        specimen._meta = input._meta;
+    }
     return specimen;
 }
 /**
@@ -124,21 +197,31 @@ function createSpecimen(input) {
  * ```
  */
 function serializeSpecimen(specimen) {
+    // WOLS v1.3.0: PRIMORDIA is never emitted as a type. A specimen object built
+    // by hand with type PRIMORDIA gets the same resolution as createSpecimen()
+    // (shared resolveTypeAndStage). Any other type is emitted as given.
+    let type = specimen.type;
+    let stage = specimen.stage;
+    const resolved = (0, types_js_1.resolveTypeAndStage)(type, stage);
+    if (resolved?.primordia) {
+        type = resolved.type;
+        stage = resolved.stage;
+    }
     // Build ordered object with JSON-LD fields first
     const ordered = {
         '@context': specimen['@context'],
         '@type': specimen['@type'],
         id: specimen.id,
         version: specimen.version,
-        type: specimen.type,
+        type,
         species: specimen.species,
     };
     // Add optional fields in order, only if defined
     if (specimen.strain !== undefined) {
         ordered['strain'] = specimen.strain;
     }
-    if (specimen.stage !== undefined) {
-        ordered['stage'] = specimen.stage;
+    if (stage !== undefined) {
+        ordered['stage'] = stage;
     }
     if (specimen.created !== undefined) {
         ordered['created'] = specimen.created;
@@ -158,6 +241,9 @@ function serializeSpecimen(specimen) {
     if (specimen.signature !== undefined) {
         ordered['signature'] = specimen.signature;
     }
+    if (specimen._meta !== undefined) {
+        ordered['_meta'] = specimen._meta;
+    }
     return JSON.stringify(ordered);
 }
 //# sourceMappingURL=specimen.js.map

package/dist/cjs/specimen.js.map

@@ -1 +1 @@
-{"version":3,"file":"specimen.js","sourceRoot":"","sources":["../../src/specimen.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"specimen.js","sourceRoot":"","sources":["../../src/specimen.ts"],"names":[],"mappings":"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"}