@tuturuuu/utils 0.0.3 → 0.6.1

package/src/search.ts

@@ -0,0 +1,355 @@
+export type IntentMatchReason =
+  | 'exact'
+  | 'prefix'
+  | 'compact'
+  | 'acronym'
+  | 'word-order'
+  | 'contains'
+  | 'fuzzy'
+  | 'typo';
+
+export type IntentSearchCandidate = {
+  aliases?: readonly string[];
+  keywords?: readonly string[];
+  subtitle?: string | null;
+  title: string;
+};
+
+export type IntentSearchResult<T extends IntentSearchCandidate> = {
+  item: T;
+  matchedText: string;
+  reason: IntentMatchReason;
+  score: number;
+};
+
+type NormalizedText = {
+  compact: string;
+  original: string;
+  text: string;
+  words: string[];
+};
+
+type CandidateMatch = {
+  matchedText: string;
+  reason: IntentMatchReason;
+  score: number;
+};
+
+const SHORT_QUERY_MAX_LENGTH = 2;
+const TYPO_DISTANCE_MAX_LENGTH = 32;
+
+export function normalizeIntentText(value: string): string {
+  return value
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/đ/g, 'd')
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim()
+    .replace(/\s+/g, ' ');
+}
+
+export function compactIntentText(value: string): string {
+  return normalizeIntentText(value).replace(/\s+/g, '');
+}
+
+export function getIntentAcronym(value: string): string {
+  return normalizeIntentText(value)
+    .split(' ')
+    .filter(Boolean)
+    .map((word) => word[0])
+    .join('');
+}
+
+function normalize(value: string): NormalizedText {
+  const text = normalizeIntentText(value);
+  const words = text ? text.split(' ') : [];
+
+  return {
+    compact: words.join(''),
+    original: value,
+    text,
+    words,
+  };
+}
+
+function getCandidateTexts(candidate: IntentSearchCandidate): string[] {
+  const values = [
+    candidate.title,
+    candidate.subtitle ?? '',
+    ...(candidate.aliases ?? []),
+    ...(candidate.keywords ?? []),
+  ]
+    .map((value) => value.trim())
+    .filter(Boolean);
+
+  return Array.from(new Set(values));
+}
+
+function hasOrderedCharacters(text: string, query: string): boolean {
+  let queryIndex = 0;
+
+  for (let i = 0; i < text.length && queryIndex < query.length; i += 1) {
+    if (text[i] === query[queryIndex]) {
+      queryIndex += 1;
+    }
+  }
+
+  return queryIndex === query.length;
+}
+
+function orderedCharacterScore(text: string, query: string): number {
+  let queryIndex = 0;
+  let firstMatch = -1;
+  let lastMatch = -1;
+  let streak = 0;
+  let longestStreak = 0;
+
+  for (let i = 0; i < text.length && queryIndex < query.length; i += 1) {
+    if (text[i] === query[queryIndex]) {
+      if (firstMatch === -1) firstMatch = i;
+      lastMatch = i;
+      queryIndex += 1;
+      streak += 1;
+      longestStreak = Math.max(longestStreak, streak);
+    } else {
+      streak = 0;
+    }
+  }
+
+  if (queryIndex !== query.length || firstMatch === -1 || lastMatch === -1) {
+    return 0;
+  }
+
+  const span = Math.max(1, lastMatch - firstMatch + 1);
+  const density = query.length / span;
+  const prefixBonus = firstMatch === 0 ? 28 : Math.max(0, 18 - firstMatch);
+  const streakBonus = Math.min(40, longestStreak * 8);
+
+  return Math.round(320 + density * 110 + prefixBonus + streakBonus);
+}
+
+function boundedLevenshtein(a: string, b: string, maxDistance: number): number {
+  if (Math.abs(a.length - b.length) > maxDistance) return maxDistance + 1;
+  if (a === b) return 0;
+  if (!a) return b.length;
+  if (!b) return a.length;
+
+  let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+  let current = new Array<number>(b.length + 1);
+
+  for (let i = 1; i <= a.length; i += 1) {
+    current[0] = i;
+    let rowMin = current[0];
+
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const deletion = (previous[j] ?? Number.POSITIVE_INFINITY) + 1;
+      const insertion = (current[j - 1] ?? Number.POSITIVE_INFINITY) + 1;
+      const substitution = (previous[j - 1] ?? Number.POSITIVE_INFINITY) + cost;
+      current[j] = Math.min(deletion, insertion, substitution);
+      rowMin = Math.min(rowMin, current[j] ?? Number.POSITIVE_INFINITY);
+    }
+
+    if (rowMin > maxDistance) return maxDistance + 1;
+    [previous, current] = [current, previous];
+  }
+
+  return previous[b.length] ?? maxDistance + 1;
+}
+
+function getTypoLimit(queryLength: number): number {
+  if (queryLength < 4) return 0;
+  if (queryLength < 8) return 1;
+  return 2;
+}
+
+function scoreText(text: string, query: NormalizedText): CandidateMatch | null {
+  const target = normalize(text);
+
+  if (!query.text || !query.compact || !target.text) return null;
+
+  const isShortQuery = query.compact.length <= SHORT_QUERY_MAX_LENGTH;
+  const acronym = getIntentAcronym(target.original);
+
+  if (target.text === query.text) {
+    return {
+      matchedText: text,
+      reason: 'exact',
+      score: 10_000,
+    };
+  }
+
+  if (target.compact === query.compact) {
+    return {
+      matchedText: text,
+      reason: 'compact',
+      score: 9_700,
+    };
+  }
+
+  if (target.text.startsWith(query.text)) {
+    return {
+      matchedText: text,
+      reason: 'prefix',
+      score: 9_200 - Math.min(300, target.text.length - query.text.length),
+    };
+  }
+
+  if (target.compact.startsWith(query.compact)) {
+    return {
+      matchedText: text,
+      reason: 'compact',
+      score:
+        8_900 - Math.min(300, target.compact.length - query.compact.length),
+    };
+  }
+
+  if (acronym?.startsWith(query.compact)) {
+    return {
+      matchedText: text,
+      reason: 'acronym',
+      score: 8_300 - Math.min(200, acronym.length - query.compact.length),
+    };
+  }
+
+  if (isShortQuery) return null;
+
+  if (
+    target.text.includes(query.text) ||
+    target.compact.includes(query.compact)
+  ) {
+    const compactIndex = target.compact.indexOf(query.compact);
+    const wordStart = target.words.some((word) => word.startsWith(query.text));
+
+    return {
+      matchedText: text,
+      reason: 'contains',
+      score: (wordStart ? 7_400 : 6_400) - Math.max(0, compactIndex),
+    };
+  }
+
+  if (
+    query.words.length > 1 &&
+    query.words.every((word) =>
+      target.words.some((targetWord) => targetWord.startsWith(word))
+    )
+  ) {
+    return {
+      matchedText: text,
+      reason: 'word-order',
+      score: 7_700 - Math.min(500, target.words.length * 20),
+    };
+  }
+
+  if (hasOrderedCharacters(target.compact, query.compact)) {
+    return {
+      matchedText: text,
+      reason: 'fuzzy',
+      score: orderedCharacterScore(target.compact, query.compact),
+    };
+  }
+
+  const typoLimit = getTypoLimit(query.compact.length);
+
+  if (
+    typoLimit > 0 &&
+    target.compact.length <= TYPO_DISTANCE_MAX_LENGTH &&
+    query.compact.length <= TYPO_DISTANCE_MAX_LENGTH
+  ) {
+    const candidates = [target.compact, ...target.words];
+    let bestDistance = typoLimit + 1;
+
+    for (const candidate of candidates) {
+      if (Math.abs(candidate.length - query.compact.length) > typoLimit) {
+        continue;
+      }
+
+      bestDistance = Math.min(
+        bestDistance,
+        boundedLevenshtein(candidate, query.compact, typoLimit)
+      );
+    }
+
+    if (bestDistance <= typoLimit) {
+      return {
+        matchedText: text,
+        reason: 'typo',
+        score: 6_900 - bestDistance * 350,
+      };
+    }
+  }
+
+  return null;
+}
+
+export function scoreIntentCandidate<T extends IntentSearchCandidate>(
+  item: T,
+  query: string
+): IntentSearchResult<T> | null {
+  const normalizedQuery = normalize(query);
+
+  if (!normalizedQuery.text) {
+    return {
+      item,
+      matchedText: item.title,
+      reason: 'exact',
+      score: 0,
+    };
+  }
+
+  let bestMatch: CandidateMatch | null = null;
+
+  for (const text of getCandidateTexts(item)) {
+    const match = scoreText(text, normalizedQuery);
+
+    if (!match) continue;
+
+    if (!bestMatch || match.score > bestMatch.score) {
+      bestMatch = match;
+    }
+  }
+
+  if (!bestMatch) return null;
+
+  return {
+    item,
+    ...bestMatch,
+  };
+}
+
+export function searchIntent<T extends IntentSearchCandidate>(
+  items: readonly T[],
+  query: string,
+  {
+    limit = 10,
+    minScore = 1,
+  }: {
+    limit?: number;
+    minScore?: number;
+  } = {}
+): IntentSearchResult<T>[] {
+  const trimmedQuery = query.trim();
+
+  if (!trimmedQuery) {
+    return items.slice(0, limit).map((item) => ({
+      item,
+      matchedText: item.title,
+      reason: 'exact',
+      score: 0,
+    }));
+  }
+
+  return items
+    .map((item, index) => {
+      const result = scoreIntentCandidate(item, trimmedQuery);
+
+      return result && result.score >= minScore ? { ...result, index } : null;
+    })
+    .filter((result): result is IntentSearchResult<T> & { index: number } =>
+      Boolean(result)
+    )
+    .sort((a, b) => b.score - a.score || a.index - b.index)
+    .slice(0, limit)
+    .map(({ index: _index, ...result }) => result);
+}

package/src/storage-display-name.ts

@@ -0,0 +1,30 @@
+const UUID_PATTERN =
+  '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+const GENERATED_STORAGE_PREFIX_PATTERN = new RegExp(
+  `^(?:${UUID_PATTERN}[-_])+`,
+  'i'
+);
+
+export function stripGeneratedStorageNamePrefix(name: string) {
+  return name.replace(GENERATED_STORAGE_PREFIX_PATTERN, '');
+}
+
+export function getStoragePathSegmentDisplayName(segment: string) {
+  let decoded = segment;
+
+  try {
+    decoded = decodeURIComponent(segment);
+  } catch {}
+
+  return stripGeneratedStorageNamePrefix(decoded);
+}
+
+export function getStorageObjectDisplayName(
+  item: { name?: string | null } | null
+) {
+  if (!item?.name) {
+    return '';
+  }
+
+  return stripGeneratedStorageNamePrefix(item.name);
+}

package/src/storage-path.ts

@@ -0,0 +1,147 @@
+/**
+ * Storage Path Sanitization Utilities
+ *
+ * Provides secure path and filename sanitization for file storage operations.
+ * Prevents directory traversal attacks and ensures safe file operations.
+ */
+
+/**
+ * Sanitizes a path component to prevent directory traversal attacks.
+ *
+ * @param path - The path string to sanitize
+ * @returns Sanitized path string, or null if the path contains invalid characters
+ *
+ * @example
+ * ```ts
+ * sanitizePath('folder/subfolder') // => 'folder/subfolder'
+ * sanitizePath('../../../etc/passwd') // => null
+ * sanitizePath('folder\\subfolder') // => 'folder/subfolder' (backslashes normalized)
+ * sanitizePath('') // => ''
+ * ```
+ */
+export function sanitizePath(path: string): string | null {
+  if (!path) return '';
+
+  // Normalize backslashes to forward slashes (Windows compatibility)
+  let sanitized = path.replace(/\\/g, '/');
+
+  // Trim and remove leading/trailing slashes
+  sanitized = sanitized.trim().replace(/^\/+|\/+$/g, '');
+
+  // Split into segments and validate each
+  const segments = sanitized.split('/').filter(Boolean);
+
+  for (const segment of segments) {
+    // Reject any segment that is '..' or '.' or empty
+    if (segment === '..' || segment === '.' || segment === '') {
+      return null;
+    }
+    // Reject segments with path traversal attempts
+    if (segment.includes('..')) {
+      return null;
+    }
+  }
+
+  // Rejoin with forward slashes
+  return segments.join('/');
+}
+
+/**
+ * Sanitizes a folder name to prevent directory traversal and invalid characters.
+ *
+ * @param name - The folder name to sanitize
+ * @returns Sanitized folder name, or null if the name contains invalid characters
+ *
+ * @example
+ * ```ts
+ * sanitizeFolderName('my-folder') // => 'my-folder'
+ * sanitizeFolderName('folder/subfolder') // => null (contains slashes)
+ * sanitizeFolderName('..') // => null (traversal attempt)
+ * sanitizeFolderName('folder\\name') // => null (normalized to 'folder/name' which contains slash)
+ * ```
+ */
+export function sanitizeFolderName(name: string): string | null {
+  if (!name) return null;
+
+  // Trim and remove leading/trailing slashes
+  const trimmed = name.trim().replace(/^\/+|\/+$/g, '');
+
+  // Replace backslashes with forward slashes
+  const normalized = trimmed.replace(/\\/g, '/');
+
+  // Reject if it contains slashes (should be a single name, not a path)
+  if (normalized.includes('/')) {
+    return null;
+  }
+
+  // Reject path traversal attempts
+  if (normalized === '..' || normalized === '.' || normalized.includes('..')) {
+    return null;
+  }
+
+  return normalized;
+}
+
+/**
+ * Sanitizes a filename to prevent directory traversal and invalid characters.
+ * Enforces strict validation rules including:
+ * - ASCII letters and digits only
+ * - Allowed special characters: space, underscore, hyphen, dot
+ * - No control characters or Unicode exploits
+ * - Maximum length of 255 characters
+ * - No leading/trailing spaces or dots
+ *
+ * @param filename - The filename to sanitize
+ * @returns Sanitized filename, or null if the filename contains invalid characters
+ *
+ * @example
+ * ```ts
+ * sanitizeFilename('document.pdf') // => 'document.pdf'
+ * sanitizeFilename('../../../etc/passwd') // => null (traversal attempt)
+ * sanitizeFilename('file\x00name.txt') // => null (control character)
+ * sanitizeFilename('very-long-name...') // => null (if exceeds 255 chars)
+ * sanitizeFilename(' .hidden') // => null (leading space/dot)
+ * ```
+ */
+export function sanitizeFilename(filename: string): string | null {
+  if (!filename) return null;
+
+  // Get the basename to remove any path components
+  // Using a simple approach without node:path for better portability
+  const lastSlash = Math.max(
+    filename.lastIndexOf('/'),
+    filename.lastIndexOf('\\')
+  );
+  const base = lastSlash >= 0 ? filename.substring(lastSlash + 1) : filename;
+
+  // Reject if basename differs from original (indicates path traversal attempt)
+  if (base !== filename) {
+    return null;
+  }
+
+  // Normalize to NFC (Canonical Decomposition, followed by Canonical Composition)
+  const normalized = base.normalize('NFC');
+
+  // Check length (255 characters max)
+  if (normalized.length === 0 || normalized.length > 255) {
+    return null;
+  }
+
+  // Reject leading/trailing spaces or dots
+  if (
+    normalized.startsWith(' ') ||
+    normalized.endsWith(' ') ||
+    normalized.startsWith('.') ||
+    normalized.endsWith('.')
+  ) {
+    return null;
+  }
+
+  // Allows: Letters, Numbers, Spaces, Dots, Underscores, Hyphens, and Parentheses
+  const allowedPattern = /^[a-zA-Z0-9\s._()/-]+$/;
+  if (!allowedPattern.test(normalized)) {
+    return null;
+  }
+
+  return normalized;
+}

package/src/tag-utils.ts

@@ -0,0 +1,159 @@
+// Tag color utilities for consistent styling across components
+
+// Dynamic color generation using HSL for better control and consistency
+// Optimized for dark mode with excellent contrast ratios
+const COLOR_PALETTE = [
+  { hue: 210, saturation: 80, lightness: 50 }, // Blue
+  { hue: 120, saturation: 80, lightness: 50 }, // Green
+  { hue: 270, saturation: 80, lightness: 50 }, // Purple
+  { hue: 30, saturation: 80, lightness: 50 }, // Orange
+  { hue: 330, saturation: 80, lightness: 50 }, // Pink
+  { hue: 180, saturation: 80, lightness: 50 }, // Cyan
+  { hue: 60, saturation: 80, lightness: 50 }, // Yellow
+  { hue: 0, saturation: 80, lightness: 50 }, // Red
+  { hue: 150, saturation: 80, lightness: 50 }, // Teal
+  { hue: 300, saturation: 80, lightness: 50 }, // Magenta
+  { hue: 90, saturation: 80, lightness: 50 }, // Lime
+  { hue: 240, saturation: 80, lightness: 50 }, // Indigo
+] as const;
+
+export const DEFAULT_TAG_COLOR =
+  'bg-gray-500/20 text-gray-300 border-gray-500/30';
+
+/**
+ * Generate HSL color values for a tag
+ * @param tag - The tag string
+ * @returns HSL color object
+ */
+function generateTagHSL(tag: string) {
+  if (!tag || typeof tag !== 'string' || tag.trim().length === 0) {
+    return { hue: 0, saturation: 0, lightness: 50 }; // Gray
+  }
+
+  // Sanitize the tag for consistent hashing
+  const sanitizedTag = tag.trim().toLowerCase();
+
+  // Enhanced hash function for better distribution
+  let hash = 0;
+  for (let i = 0; i < sanitizedTag.length; i++) {
+    const charCode = sanitizedTag.charCodeAt(i);
+    if (charCode !== undefined) {
+      hash = (hash << 5) - hash + charCode;
+      hash = hash & hash; // Convert to 32-bit integer
+    }
+  }
+
+  const index = Math.abs(hash) % COLOR_PALETTE.length;
+  const baseColor = COLOR_PALETTE[index]; // Safe since index is within bounds
+
+  if (!baseColor) {
+    return { hue: 0, saturation: 0, lightness: 50 }; // Fallback to gray
+  }
+
+  // Add some variation based on the hash to create more unique colors
+  // Reduced variation for more consistent and readable colors
+  const hueVariation = (hash % 20) - 10; // ±10 degrees (reduced from ±15)
+  const saturationVariation = (hash % 15) - 7; // ±7% (reduced from ±10%)
+  const lightnessVariation = (hash % 12) - 6; // ±6% (reduced from ±8%)
+
+  return {
+    hue: (baseColor.hue + hueVariation + 360) % 360,
+    saturation: Math.max(
+      60,
+      Math.min(85, baseColor.saturation + saturationVariation)
+    ),
+    lightness: Math.max(
+      50,
+      Math.min(70, baseColor.lightness + lightnessVariation)
+    ),
+  };
+}
+
+/**
+ * Generate a consistent color for a tag based on its text
+ * Optimized for both light and dark modes with excellent contrast
+ * @param tag - The tag string
+ * @returns CSS variables object for the tag color styling
+ */
+export function getTagColor(tag: string): {
+  '--tag-bg-color': string;
+  '--tag-text-color': string;
+  '--tag-border-color': string;
+} {
+  if (!tag || typeof tag !== 'string') {
+    return {
+      '--tag-bg-color': 'rgb(75 85 99 / 0.2)',
+      '--tag-text-color': 'rgb(209 213 219)',
+      '--tag-border-color': 'rgb(75 85 99 / 0.4)',
+    };
+  }
+
+  const hsl = generateTagHSL(tag);
+
+  // Dark mode optimized color generation
+  // Background: Dark but visible (15-25% lightness)
+  const bgLightness = Math.max(12, Math.min(25, hsl.lightness - 40));
+  const bgSaturation = Math.max(40, Math.min(80, hsl.saturation - 10));
+
+  // Text: Bright and highly visible (85-95% lightness)
+  const textLightness = Math.max(80, Math.min(95, hsl.lightness + 30));
+  const textSaturation = Math.max(60, Math.min(90, hsl.saturation + 15));
+
+  // Border: Medium brightness for definition (30-50% lightness)
+  const borderLightness = Math.max(25, Math.min(50, hsl.lightness - 25));
+  const borderSaturation = Math.max(50, Math.min(85, hsl.saturation));
+
+  return {
+    '--tag-bg-color': `hsl(${hsl.hue} ${bgSaturation}% ${bgLightness}% / 0.9)`,
+    '--tag-text-color': `hsl(${hsl.hue} ${textSaturation}% ${textLightness}%)`,
+    '--tag-border-color': `hsl(${hsl.hue} ${borderSaturation}% ${borderLightness}% / 0.6)`,
+  };
+}
+
+/**
+ * Get a static Tailwind class for tag styling that works with CSS variables
+ * @returns A CSS class string that uses CSS variables for dynamic colors
+ */
+export function getTagColorClass(): string {
+  return 'bg-[var(--tag-bg-color)] text-[var(--tag-text-color)] border-[var(--tag-border-color)]';
+}
+
+/**
+ * Get tag color styling that combines CSS variables with static Tailwind classes
+ * @param tag - The tag string
+ * @returns An object with style (CSS variables) and className (static Tailwind classes)
+ */
+export function getTagColorStyling(tag: string): {
+  style: React.CSSProperties;
+  className: string;
+} {
+  const cssVars = getTagColor(tag);
+  return {
+    style: cssVars as React.CSSProperties,
+    className: getTagColorClass(),
+  };
+}
+
+/**
+ * Get a list of available tag colors
+ * Optimized for dark mode with better contrast
+ * @returns Array of tag color classes
+ */
+export function getAvailableTagColors(): readonly string[] {
+  // Use predefined Tailwind classes optimized for dark mode
+  // These provide better contrast ratios in dark themes
+  return [
+    'bg-blue-600/20 text-blue-300 border-blue-600/40',
+    'bg-green-600/20 text-green-300 border-green-600/40',
+    'bg-purple-600/20 text-purple-300 border-purple-600/40',
+    'bg-orange-600/20 text-orange-300 border-orange-600/40',
+    'bg-pink-600/20 text-pink-300 border-pink-600/40',
+    'bg-cyan-600/20 text-cyan-300 border-cyan-600/40',
+    'bg-yellow-600/20 text-yellow-300 border-yellow-600/40',
+    'bg-red-600/20 text-red-300 border-red-600/40',
+    'bg-teal-600/20 text-teal-300 border-teal-600/40',
+    'bg-fuchsia-600/20 text-fuchsia-300 border-fuchsia-600/40',
+    'bg-lime-600/20 text-lime-300 border-lime-600/40',
+    'bg-indigo-600/20 text-indigo-300 border-indigo-600/40',
+  ] as const;
+}