glost 0.4.0 → 0.5.0

package/src/guards.ts

@@ -1,341 +0,0 @@
-// ============================================================================
-// GLOST Type Guards for Better Developer Experience
-// ============================================================================
-
-import type {
-  GLOSTParagraph,
-  GLOSTPunctuation,
-  GLOSTRoot,
-  GLOSTSentence,
-  GLOSTSource,
-  GLOSTSymbol,
-  GLOSTText,
-  GLOSTWhiteSpace,
-  GLOSTWord,
-  GLOSTNode,
-} from "./types.js";
-
-// ============================================================================
-// Core Node Type Guards
-// ============================================================================
-
-/**
- * Type guard to check if a node is an GLOSTWord
- */
-export function isGLOSTWord(node: unknown): node is GLOSTWord {
-  return (
-    typeof node === "object" &&
-    node !== null &&
-    "type" in node &&
-    node.type === "WordNode" &&
-    "children" in node &&
-    "lang" in node &&
-    "script" in node &&
-    "level" in node &&
-    "metadata" in node &&
-    "transcription" in node &&
-    "extras" in node
-  );
-}
-
-/**
- * Type guard to check if a node is an GLOSTSentence
- */
-export function isGLOSTSentence(node: unknown): node is GLOSTSentence {
-  return (
-    typeof node === "object" &&
-    node !== null &&
-    "type" in node &&
-    node.type === "SentenceNode" &&
-    "children" in node &&
-    "lang" in node &&
-    "script" in node &&
-    "level" in node &&
-    "metadata" in node
-  );
-}
-
-/**
- * Type guard to check if a node is an GLOSTParagraph
- */
-export function isGLOSTParagraph(node: unknown): node is GLOSTParagraph {
-  return (
-    typeof node === "object" &&
-    node !== null &&
-    "type" in node &&
-    node.type === "ParagraphNode" &&
-    "children" in node &&
-    "lang" in node &&
-    "script" in node &&
-    "level" in node &&
-    "metadata" in node
-  );
-}
-
-/**
- * Type guard to check if a node is an GLOSTRoot
- */
-export function isGLOSTRoot(node: unknown): node is GLOSTRoot {
-  return (
-    typeof node === "object" &&
-    node !== null &&
-    "type" in node &&
-    node.type === "RootNode" &&
-    "children" in node &&
-    "lang" in node &&
-    "script" in node &&
-    "level" in node &&
-    "metadata" in node
-  );
-}
-
-/**
- * Type guard to check if a node is an GLOSTText
- */
-export function isGLOSTText(node: unknown): node is GLOSTText {
-  return (
-    typeof node === "object" &&
-    node !== null &&
-    "type" in node &&
-    node.type === "TextNode" &&
-    "value" in node &&
-    typeof node.value === "string"
-  );
-}
-
-/**
- * Type guard to check if a node is an GLOSTPunctuation
- */
-export function isGLOSTPunctuation(node: unknown): node is GLOSTPunctuation {
-  return (
-    typeof node === "object" &&
-    node !== null &&
-    "type" in node &&
-    node.type === "PunctuationNode" &&
-    "value" in node &&
-    typeof node.value === "string"
-  );
-}
-
-/**
- * Type guard to check if a node is an GLOSTSymbol
- */
-export function isGLOSTSymbol(node: unknown): node is GLOSTSymbol {
-  return (
-    typeof node === "object" &&
-    node !== null &&
-    "type" in node &&
-    node.type === "SymbolNode" &&
-    "value" in node &&
-    typeof node.value === "string"
-  );
-}
-
-/**
- * Type guard to check if a node is an GLOSTWhiteSpace
- */
-export function isGLOSTWhiteSpace(node: unknown): node is GLOSTWhiteSpace {
-  return (
-    typeof node === "object" &&
-    node !== null &&
-    "type" in node &&
-    node.type === "WhiteSpaceNode" &&
-    "value" in node &&
-    typeof node.value === "string"
-  );
-}
-
-/**
- * Type guard to check if a node is an GLOSTSource
- */
-export function isGLOSTSource(node: unknown): node is GLOSTSource {
-  return (
-    typeof node === "object" &&
-    node !== null &&
-    "type" in node &&
-    node.type === "SourceNode" &&
-    "value" in node &&
-    typeof node.value === "string"
-  );
-}
-
-// ============================================================================
-// Content Type Guards
-// ============================================================================
-
-/**
- * Type guard to check if a node is GLOSTNode (any GLOST node)
- */
-export function isGLOSTNode(node: unknown): node is GLOSTNode {
-  return (
-    isGLOSTWord(node) ||
-    isGLOSTSentence(node) ||
-    isGLOSTParagraph(node) ||
-    isGLOSTText(node) ||
-    isGLOSTPunctuation(node) ||
-    isGLOSTSymbol(node) ||
-    isGLOSTWhiteSpace(node) ||
-    isGLOSTSource(node) ||
-    isGLOSTRoot(node)
-  );
-}
-
-// ============================================================================
-// Document Type Guards
-// ============================================================================
-
-/**
- * Type guard to check if a node is an GLOSTDocument (Root or Content)
- */
-export function isGLOSTDocument(node: unknown): node is GLOSTRoot {
-  return isGLOSTRoot(node);
-}
-
-// ============================================================================
-// Array Type Guards
-// ============================================================================
-
-/**
- * Type guard to check if an array contains only GLOSTWord nodes
- */
-export function isGLOSTWordArray(nodes: unknown[]): nodes is GLOSTWord[] {
-  return nodes.every(isGLOSTWord);
-}
-
-/**
- * Type guard to check if an array contains only GLOSTSentence nodes
- */
-export function isGLOSTSentenceArray(nodes: unknown[]): nodes is GLOSTSentence[] {
-  return nodes.every(isGLOSTSentence);
-}
-
-/**
- * Type guard to check if an array contains only GLOSTParagraph nodes
- */
-export function isGLOSTParagraphArray(nodes: unknown[]): nodes is GLOSTParagraph[] {
-  return nodes.every(isGLOSTParagraph);
-}
-
-/**
- * Type guard to check if an array contains only GLOSTContent nodes
- */
-export function isGLOSTContentArray(nodes: unknown[]): nodes is (GLOSTWord | GLOSTSentence | GLOSTParagraph | GLOSTText | GLOSTPunctuation | GLOSTSymbol | GLOSTWhiteSpace | GLOSTSource)[] {
-  return nodes.every(node => 
-    isGLOSTWord(node) ||
-    isGLOSTSentence(node) ||
-    isGLOSTParagraph(node) ||
-    isGLOSTText(node) ||
-    isGLOSTPunctuation(node) ||
-    isGLOSTSymbol(node) ||
-    isGLOSTWhiteSpace(node) ||
-    isGLOSTSource(node)
-  );
-}
-
-// ============================================================================
-// Utility Type Guards
-// ============================================================================
-
-/**
- * Type guard to check if a node has children
- */
-export function hasChildren(node: unknown): node is { children: unknown[] } {
-  return (
-    typeof node === "object" &&
-    node !== null &&
-    "children" in node &&
-    Array.isArray(node.children)
-  );
-}
-
-/**
- * Type guard to check if a node has metadata
- */
-export function hasMetadata(node: unknown): node is { metadata: Record<string, unknown> } {
-  return (
-    typeof node === "object" &&
-    node !== null &&
-    "metadata" in node &&
-    typeof node.metadata === "object" &&
-    node.metadata !== null
-  );
-}
-
-/**
- * Type guard to check if a node has transcription
- */
-export function hasTranscription(node: unknown): node is { transcription: Record<string, unknown> } {
-  return (
-    typeof node === "object" &&
-    node !== null &&
-    "transcription" in node &&
-    typeof node.transcription === "object" &&
-    node.transcription !== null
-  );
-}
-
-/**
- * Type guard to check if a node has extras
- */
-export function hasExtras(node: unknown): node is { extras: Record<string, unknown> } {
-  return (
-    typeof node === "object" &&
-    node !== null &&
-    "extras" in node &&
-    typeof node.extras === "object" &&
-    node.extras !== null
-  );
-}
-
-// ============================================================================
-// Validation Helpers
-// ============================================================================
-
-/**
- * Check if a node has valid GLOST structure (type guard based validation)
- * For schema-based validation, use validateGLOSTNode from validators.ts
- */
-export function isGLOSTNodeWithValidChildren(node: unknown): node is GLOSTNode {
-  if (!isGLOSTNode(node)) {
-    return false;
-  }
-
-  // Additional validation for nodes with children
-  if (hasChildren(node)) {
-    return (node.children as unknown[]).every(isGLOSTNode);
-  }
-
-  return true;
-}
-
-/**
- * Check if an array contains valid GLOST nodes (type guard based)
- */
-export function isGLOSTNodeArrayValid(nodes: unknown[]): nodes is GLOSTNode[] {
-  return nodes.every(isGLOSTNodeWithValidChildren);
-}
-
-/**
- * Check if a node is a leaf node (no children)
- */
-export function isLeafNode(node: GLOSTNode): boolean {
-  return (
-    isGLOSTText(node) ||
-    isGLOSTPunctuation(node) ||
-    isGLOSTSymbol(node) ||
-    isGLOSTWhiteSpace(node) ||
-    isGLOSTSource(node)
-  );
-}
-
-/**
- * Check if a node is a container node (has children)
- */
-export function isContainerNode(node: GLOSTNode): boolean {
-  return (
-    isGLOSTWord(node) ||
-    isGLOSTSentence(node) ||
-    isGLOSTParagraph(node) ||
-    isGLOSTRoot(node)
-  );
-}

package/src/nodes.ts

@@ -1,326 +0,0 @@
-import type {
-  LanguageCode,
-  LinguisticMetadata,
-  GLOSTExtras,
-  GLOSTParagraph,
-  GLOSTPunctuation,
-  GLOSTRoot,
-  GLOSTSentence,
-  GLOSTSymbol,
-  GLOSTText,
-  GLOSTWhiteSpace,
-  GLOSTWord,
-  ScriptSystem,
-  TransliterationData,
-} from "./types.js";
-
-// ============================================================================
-// Options Interfaces
-// ============================================================================
-
-/**
- * Options for creating a GLOST word node
- */
-export interface CreateWordNodeOptions {
-  /** The text value of the word */
-  value: string;
-  /** Transcription data (IPA, romanization, etc.) */
-  transcription: TransliterationData;
-  /** Linguistic metadata (part of speech, etc.) */
-  metadata: LinguisticMetadata;
-  /** Language code (ISO-639-1, ISO-639-3, or BCP-47) */
-  lang?: LanguageCode;
-  /** Script system used */
-  script?: ScriptSystem;
-  /** Additional extension data */
-  extras?: GLOSTExtras;
-}
-
-/**
- * Options for creating a GLOST sentence node
- */
-export interface CreateSentenceNodeOptions {
-  /** The original text of the sentence */
-  originalText: string;
-  /** Language code */
-  lang: LanguageCode;
-  /** Script system used */
-  script: ScriptSystem;
-  /** Word nodes in the sentence */
-  children?: GLOSTWord[];
-  /** Optional transcription data */
-  transcription?: TransliterationData;
-  /** Additional extension data */
-  extras?: GLOSTExtras;
-}
-
-/**
- * Options for creating a GLOST root node
- */
-export interface CreateRootNodeOptions {
-  /** Language code */
-  lang: LanguageCode;
-  /** Script system used */
-  script: ScriptSystem;
-  /** Paragraph nodes */
-  children?: GLOSTParagraph[];
-  /** Document metadata */
-  metadata?: {
-    title?: string;
-    author?: string;
-    date?: string;
-    description?: string;
-  };
-  /** Additional extension data */
-  extras?: GLOSTExtras;
-}
-
-/**
- * Options for creating a simple word node
- */
-export interface CreateSimpleWordOptions {
-  /** The text value of the word */
-  text: string;
-  /** Transliteration text */
-  transliteration: string;
-  /** Transcription system (default: "ipa") */
-  system?: string;
-  /** Part of speech (default: "unknown") */
-  partOfSpeech?: string;
-}
-
-
-// ============================================================================
-// Node Factory Functions
-// ============================================================================
-
-/**
- * Create a GLOST word node
- *
- * @example
- * ```typescript
- * const word = createGLOSTWordNode({
- *   value: "hello",
- *   transcription: { ipa: { text: "həˈloʊ", system: "ipa" } },
- *   metadata: { partOfSpeech: "interjection" },
- *   lang: "en",
- *   script: "latin"
- * });
- * ```
- */
-export function createGLOSTWordNode(options: CreateWordNodeOptions): GLOSTWord {
-  const { value, transcription, metadata, lang, script, extras } = options;
-  return {
-    type: "WordNode",
-    lang,
-    script,
-    transcription,
-    metadata,
-    extras,
-    children: [createGLOSTTextNode(value)],
-  };
-}
-
-/**
- * Create a GLOST sentence node
- *
- * @example
- * ```typescript
- * const sentence = createGLOSTSentenceNode({
- *   originalText: "Hello world",
- *   lang: "en",
- *   script: "latin",
- *   children: [wordNode1, wordNode2]
- * });
- * ```
- */
-export function createGLOSTSentenceNode(
-  options: CreateSentenceNodeOptions,
-): GLOSTSentence {
-  const {
-    originalText,
-    lang,
-    script,
-    children = [],
-    transcription,
-    extras,
-  } = options;
-  return {
-    type: "SentenceNode",
-    originalText,
-    lang,
-    script,
-    transcription,
-    children,
-    extras,
-  };
-}
-
-/**
- * Create a GLOST paragraph node
- */
-export function createGLOSTParagraphNode(
-  children: GLOSTSentence[] = [],
-  extras?: GLOSTExtras,
-): GLOSTParagraph {
-  return {
-    type: "ParagraphNode",
-    children,
-    position: undefined,
-    extras,
-  };
-}
-
-/**
- * Create a GLOST root node
- *
- * @example
- * ```typescript
- * const root = createGLOSTRootNode({
- *   lang: "en",
- *   script: "latin",
- *   children: [paragraphNode],
- *   metadata: { title: "My Document" }
- * });
- * ```
- */
-export function createGLOSTRootNode(options: CreateRootNodeOptions): GLOSTRoot {
-  const { lang, script, children = [], metadata, extras } = options;
-  return {
-    type: "RootNode",
-    lang,
-    script,
-    metadata,
-    children,
-    position: undefined,
-    extras,
-  };
-}
-
-// ============================================================================
-// Helper Functions for Common Patterns
-// ============================================================================
-
-/**
- * Create a simple word node with basic transcription
- *
- * @example
- * ```typescript
- * const word = createSimpleWord({
- *   text: "hello",
- *   transliteration: "həˈloʊ",
- *   system: "ipa",
- *   partOfSpeech: "interjection"
- * });
- * ```
- */
-export function createSimpleWord(options: CreateSimpleWordOptions): GLOSTWord {
-  const { text, transliteration, system = "ipa", partOfSpeech = "unknown" } = options;
-
-  const transcription: TransliterationData = {
-    [system]: {
-      text: transliteration,
-      syllables: [text],
-    },
-  };
-
-  const metadata: LinguisticMetadata = {
-    partOfSpeech,
-  };
-
-  return createGLOSTWordNode({ value: text, transcription, metadata });
-}
-
-
-/**
- * Create a sentence from an array of words
- */
-export function createSentenceFromWords(
-  words: GLOSTWord[],
-  lang: LanguageCode,
-  script: ScriptSystem,
-  originalText?: string,
-): GLOSTSentence {
-  const text =
-    originalText ||
-    words
-      .map((w) => {
-        // Extract text from word's Text node children
-        const textNode = w.children.find(
-          (child) => child.type === "TextNode",
-        ) as GLOSTText;
-        return textNode ? textNode.value : "";
-      })
-      .join("");
-  return createGLOSTSentenceNode({ originalText: text, lang, script, children: words });
-}
-
-/**
- * Create a paragraph from an array of sentences
- */
-export function createParagraphFromSentences(
-  sentences: GLOSTSentence[],
-): GLOSTParagraph {
-  return createGLOSTParagraphNode(sentences);
-}
-
-/**
- * Create a document from an array of paragraphs
- */
-export function createDocumentFromParagraphs(
-  paragraphs: GLOSTParagraph[],
-  lang: LanguageCode,
-  script: ScriptSystem,
-  metadata?: {
-    title?: string;
-    author?: string;
-    date?: string;
-    description?: string;
-  },
-): GLOSTRoot {
-  return createGLOSTRootNode({ lang, script, children: paragraphs, metadata });
-}
-
-// ============================================================================
-// NLCST Node Factory Functions
-// ============================================================================
-
-/**
- * Create a GLOST punctuation node
- */
-export function createGLOSTPunctuationNode(value: string): GLOSTPunctuation {
-  return {
-    type: "PunctuationNode",
-    value,
-  };
-}
-
-/**
- * Create a GLOST whitespace node
- */
-export function createGLOSTWhiteSpaceNode(value: string): GLOSTWhiteSpace {
-  return {
-    type: "WhiteSpaceNode",
-    value,
-  };
-}
-
-/**
- * Create a GLOST symbol node
- */
-export function createGLOSTSymbolNode(value: string): GLOSTSymbol {
-  return {
-    type: "SymbolNode",
-    value,
-  };
-}
-
-/**
- * Create a GLOST text node
- */
-export function createGLOSTTextNode(value: string): GLOSTText {
-  return {
-    type: "TextNode",
-    value,
-  };
-}