API surface

Every public export from @koda.oss/glyph, grouped by layer.

Deep docs live under Core, Index, Query, Collections, Completions, and Spotlight.

Core

Functions

Export	Signature	Doc
Create	(text, options?) => GlyphRecord	Create
Compare	(a, b, options?) => GlyphComparisonResult	Compare
CompareGlyphs	(a, b, options?) => GlyphComparisonResult	Compare
CreateGroup	(glyphs: Glyph[] | string[]) => GlyphGroup	Groups
CompareGroups	(group1, group2, options?) => GlyphComparisonResult	Groups
GroupResultAggregatorMax	GroupResultAggregator	Groups
GroupResultAggregatorSum	GroupResultAggregator	Groups
Serialize	(Glyph | GlyphSignature | GlyphRecord) => string	Serialize
Deserialize	(string) => Glyph	Serialize
CreateTokens	(text, normalize?) => GlyphToken[]	Tokenize
CreateUnigrams	(text, normalize?) => GlyphUnigram[]	Tokenize
CreateVGrams	(text, vgramSize, normalize?) => GlyphVGram[]	Tokenize
Tokenize	(text, options?) => GlyphTokenizationResult	Tokenize
TextFilter	(text) => string	Text normalization
TextStrip	(text) => string	Text normalization
index.New	(options?) => GlyphIndexInstance	Index

Core types

type Glyph = Uint32Array & { readonly __glyph: true };
type GlyphGroup = Record<string, Glyph>;
type GlyphGroupInput = GlyphGroup | Glyph[];
type GlyphToken = string;
type GlyphUnigram = string;
type GlyphVGram = string;

interface GlyphSignature {
  version: number;
  glyph: Glyph;
}

interface GlyphRecord extends GlyphSignature {
  createdAt: number;
}

interface GlyphCreateOptions {
  size?: number;        // default 128
  vgramSize?: number;   // default 4
  normalize?: boolean;  // default true
}

interface GlyphTokenizationOptions {
  vgramSize?: number;   // default 2 in Tokenize()
  normalize?: boolean;  // default true
}

interface GlyphTokenizationResult {
  tokens: GlyphToken[];
  unigrams: GlyphUnigram[];
  vgrams: GlyphVGram[];
}

interface GlyphComparisonResult {
  similarity: number;
  distance: number;
  matches: number;
  size: number;
  matchedLeft?: string | number;
  matchedRight?: string | number;
}


interface GlyphComparisonOptions {
  aggregate?: GroupResultAggregator;
}

type GroupResultAggregatorContext = {
  scores: number[];
  left: GlyphGroup;
  right: GlyphGroup;
};

type GroupResultAggregator = (context: GroupResultAggregatorContext) => number;

type GlyphIndexMode = "bands" | "direct";

interface GlyphIndexOptions {
  mode?: GlyphIndexMode;   // default "bands"
  bands?: number;          // default 64 when size is 128
  rows?: number;           // default 2 when size is 128
  glyphSize?: number;
}

interface GlyphIndexInstance {
  readonly mode: GlyphIndexMode;
  Get(key: string): Glyph | GlyphGroup | undefined;
  Set(key: string, glyphs?: Glyph | GlyphGroupInput): void;
  Add(key: string, glyphs: Glyph | GlyphGroupInput): void;
  Remove(key: string): void;
  Has(key: string): boolean;
  Clear(): void;
  Size(): number;
  Keys(): IterableIterator<string>;
  Values(): IterableIterator<Glyph | GlyphGroup>;
  Entries(): IterableIterator<[string, Glyph | GlyphGroup]>;
  CandidateKeys(
    probe: Glyph | GlyphSignature | GlyphGroupInput,
  ): IterableIterator<string>;
}

See Glyph and Index for type notes.

Query

Functions

Export	Signature	Doc
query.New	(index) => GlyphQueryInstance	Query

Query types

interface GlyphQueryInstance {
  Search(
    probe: Glyph | GlyphSignature | GlyphGroupInput,
    options?: GlyphQueryOptions,
  ): GlyphQueryResult[];
}

interface GlyphQueryOptions {
  limit?: number;
  threshold?: number;      // default 0
  normalize?: boolean;     // default false
  aggregate?: GroupResultAggregator;
  compare?: GlyphComparisonOptions;
}

interface GlyphQueryResult {
  key: string;
  similarity: number;
  comparison: GlyphComparisonResult;
  matched?: string | number;
}

Result fields: Query results.

Collections

Functions

Export	Signature	Doc
collections.New	(options?) => GlyphCollectionInstance	Collections
CollectionAggregatorMin	CollectionAggregator	Aggregators
CollectionAggregatorMax	CollectionAggregator	Aggregators
CollectionAggregatorMean	CollectionAggregator	Aggregators
CollectionAggregatorMid	CollectionAggregator	Aggregators
CollectionAggregatorSum	CollectionAggregator	Aggregators
CollectionAggregatorSoftmax	CollectionAggregator	Aggregators

Collections types

type CollectionAggregatorContext = {
  collection: GlyphGroup;
  index: number;
};

type CollectionAggregator = (
  values: number[],
  context?: CollectionAggregatorContext,
) => number;

interface GlyphCollectionOptions {
  create?: GlyphCreateOptions;
  aggregator?: CollectionAggregator; // default CollectionAggregatorSoftmax
}

interface GlyphCollectionInstance {
  readonly glyph: Glyph;
  Add(key: string, example: string | Glyph): void;
  AddGroup(group: GlyphGroupInput): void;
  Remove(key: string): void;
  Clear(): void;
  Collection(): GlyphGroup;
  Has(key: string): boolean;
  Count(): number;
}

See Collections and Aggregators.

Completions

Functions

Export	Signature	Doc
completions.New	(options?) => CompletionChainInstance	Chain

Completions types

interface GlyphCompletionChainOptions {
  order?: number;               // default 3
  create?: GlyphCreateOptions;
}

interface GlyphCompletionOptions {
  limit?: number;    // default 5
  minCount?: number; // default 1
}

interface GlyphCompletionResult {
  token: string;
  score: number;
  count: number;
  comparison: GlyphComparisonResult;
  source: {
    key: string;
    glyph: Glyph;
  };
}

interface CompletionChainInstance {
  Ingest(key: string, text: string): void;
  Complete(prefix: string, options?: GlyphCompletionOptions): GlyphCompletionResult[];
  Clear(): void;
  Size(): number;
}

Result fields: Completion results.

Spotlight

Functions

Export	Signature	Doc
spotlight.New	(content, options?) => GlyphSpotlightDocumentInstance	Document

Spotlight types

type GlyphSpotlightChunk = string;
type GlyphSpotlightChunker = (text: string) => GlyphSpotlightChunk[];

type GlyphSpotlightCompiledChunk = {
  text: string;
  glyph: Glyph;
  length: number;
};

interface GlyphSpotlightOptions {
  normalize?: boolean;
  create?: GlyphCreateOptions;
  aggregate?: GroupResultAggregator;  // default GroupResultAggregatorSum for group probes
  chunker?: GlyphSpotlightChunker;
  textOutput?: boolean;        // default false
}

interface GlyphSpotlightQueryOptions extends GlyphSpotlightOptions {
  limit?: number;
  threshold?: number;          // default 0
}

interface GlyphSpotlightRankOptions extends GlyphSpotlightOptions {}

interface GlyphSpotlightResult extends GlyphSpotlightCompiledChunk {
  score: number;
  comparison: GlyphComparisonResult;
  matched?: string | number;
}

interface GlyphSpotlightDocumentInstance {
  Rank(probe, options?): GlyphSpotlightResult[] | string[];
  Query(probe, options?): GlyphSpotlightResult[] | string[];
  Chunks(): readonly GlyphSpotlightCompiledChunk[];
  Size(): number;
}

See Document, Rank, Query.

Errors

Named error classes exported from @koda.oss/glyph:

Export	When thrown
GlyphSizeMismatchError	Compare or collection operations receive glyphs of different lengths
EmptyGroupError	Group compare runs on an empty group (default message: "Cannot compare empty glyph groups")
InvalidSerializedGlyphError	Deserialize() receives malformed or unsupported serialized glyph data