glost 0.2.0 → 0.4.0

package/src/index.ts

@@ -1,15 +1,16 @@
 // GLOST - Glossed Syntax Tree
 // Extends nlcst for language learning with annotations
 
-export * from "./types";
-export * from "./nodes";
-export * from "./utils";
-export * from "./validators";
-export * from "./guards";
-// export * from './example';
+export * from "./types.js";
+export * from "./nodes.js";
+export * from "./utils.js";
+export * from "./validators.js";
+export * from "./guards.js";
+export * from "./errors.js";
+// export * from './example.js';
 
 // Re-export utility types
-export type { ParagraphLike } from "./utils";
+export type { ParagraphLike } from "./utils.js";
 
 // Re-export key utilities for transcription components
 export {
@@ -65,4 +66,4 @@ export {
   getLanguageFallback,
   normalizeLanguageTag,
   isValidLanguageTag,
-} from "./utils";
+} from "./utils.js";

package/src/nodes.ts

@@ -12,7 +12,7 @@ import type {
   GLOSTWord,
   ScriptSystem,
   TransliterationData,
-} from "./types";
+} from "./types.js";
 
 // ============================================================================
 // Options Interfaces
@@ -220,7 +220,6 @@ export function createSimpleWord(options: CreateSimpleWordOptions): GLOSTWord {
   const transcription: TransliterationData = {
     [system]: {
       text: transliteration,
-      system: system as any,
       syllables: [text],
     },
   };

package/src/types.ts

@@ -188,7 +188,7 @@ export type ExtendedMetadata = {
   /** Quick translations in multiple languages */
   translations?: QuickTranslations;
   /** Difficulty level for learners */
-  difficulty?: "beginner" | "intermediate" | "advanced";
+  difficulty?: "beginner" | "intermediate" | "advanced" | 1 | 2 | 3 | 4 | 5 | string;
   /** Frequency in common usage */
   frequency?: "rare" | "uncommon" | "common" | "very-common";
   /** Cultural notes */
@@ -203,15 +203,30 @@ export type ExtendedMetadata = {
 
 /**
  * Extras field for extending GLOST nodes
+ * 
+ * This interface can be augmented by extension packages via declaration merging.
+ * 
+ * @example
+ * ```typescript
+ * // In an extension package
+ * declare module "glost" {
+ *   interface GLOSTExtras {
+ *     frequency?: {
+ *       rank: number;
+ *       category: "very-common" | "common" | "uncommon" | "rare";
+ *     };
+ *   }
+ * }
+ * ```
  */
-export type GLOSTExtras = {
+export interface GLOSTExtras {
   /** Quick translations */
   translations?: QuickTranslations;
   /** Extended metadata */
   metadata?: ExtendedMetadata;
-  /** Custom extensions */
-  [key: string]: any;
-};
+  /** Custom extensions - allows any string key with unknown value */
+  [key: string]: unknown;
+}
 
 // ============================================================================
 // Transcription and Pronunciation Types
@@ -231,12 +246,13 @@ export type PronunciationVariant = {
 
 /**
  * Transcription information for a text segment
+ * 
+ * Note: The transcription system is not stored in this object.
+ * It is the key in the TransliterationData record.
  */
 export type TranscriptionInfo = {
   /** The transcription text */
   text: string;
-  /** The transcription system used */
-  system: TranscriptionSystem;
   /** Pronunciation variants */
   variants?: PronunciationVariant[];
   /** Tone information (for tonal languages) */
@@ -284,7 +300,7 @@ export type LinguisticMetadata = {
   /** @deprecated Use extras.translations instead */
   fullDefinition?: string;
   /** @deprecated Use metadata enrichment extensions instead */
-  difficulty?: "beginner" | "intermediate" | "advanced";
+  difficulty?: "beginner" | "intermediate" | "advanced" | 1 | 2 | 3 | 4 | 5 | string;
 };
 
 // ============================================================================
@@ -367,7 +383,7 @@ export type GLOSTWord = Omit<NlcstWord, "children"> & {
   /** @deprecated Use extras.translations instead */
   fullDefinition?: string;
   /** @deprecated Use metadata enrichment extensions instead */
-  difficulty?: "beginner" | "intermediate" | "advanced";
+  difficulty?: "beginner" | "intermediate" | "advanced" | 1 | 2 | 3 | 4 | 5 | string;
   /** Language code for this node */
   lang?: LanguageCode;
   /** Script system used */

package/src/utils.ts

@@ -13,7 +13,7 @@ import type {
   GLOSTSyllable,
   GLOSTWord,
   TranscriptionSystem,
-} from "./types";
+} from "./types.js";
 
 // ============================================================================
 // BCP-47 Language Tag Utilities
@@ -517,7 +517,7 @@ export function getWordPartOfSpeech(word: GLOSTWord): string {
 /**
  * Get word difficulty
  */
-export function getWordDifficulty(word: GLOSTWord): string {
+export function getWordDifficulty(word: GLOSTWord): string | number {
   return word.difficulty ?? word.extras?.metadata?.difficulty ?? "";
 }