@morscherlab/mint-sdk 1.0.12 → 1.0.14

package/src/composables/useFileImport.ts

@@ -0,0 +1,231 @@
+import { ref, shallowRef, type Ref, type ShallowRef } from 'vue'
+
+export interface DelimitedTable {
+  columns: string[]
+  rows: Record<string, string>[]
+  rawRows: string[][]
+  delimiter: string
+}
+
+export interface ParseDelimitedTextOptions {
+  delimiter?: string
+  headers?: readonly string[]
+  hasHeaderRow?: boolean
+  trim?: boolean
+}
+
+export interface FileImportValidationOptions {
+  accept?: string | readonly string[]
+  maxSizeBytes?: number
+}
+
+export interface FileImportOptions<TResult = string> extends FileImportValidationOptions {
+  encoding?: string
+  parse?: (text: string, file: File) => TResult | Promise<TResult>
+}
+
+export interface UseFileImportReturn<TResult> {
+  loading: ShallowRef<boolean>
+  error: Ref<string | null>
+  fileName: Ref<string>
+  result: Ref<TResult | null>
+  importFile: (file: File) => Promise<TResult>
+  clear: () => void
+}
+
+/** Stateful file reader for plugin import flows with shared validation and error handling. */
+export function useFileImport<TResult = string>(
+  options: FileImportOptions<TResult> = {},
+): UseFileImportReturn<TResult> {
+  const loading = shallowRef(false)
+  const error = ref<string | null>(null)
+  const fileName = ref('')
+  const result = ref<TResult | null>(null) as Ref<TResult | null>
+
+  function clear(): void {
+    loading.value = false
+    error.value = null
+    fileName.value = ''
+    result.value = null
+  }
+
+  async function importFile(file: File): Promise<TResult> {
+    loading.value = true
+    error.value = null
+    fileName.value = file.name
+
+    try {
+      validateImportFile(file, options)
+      const text = await readFileAsText(file, options.encoding)
+      const parsed = options.parse
+        ? await options.parse(text, file)
+        : text as TResult
+      result.value = parsed
+      return parsed
+    } catch (err) {
+      const message = readErrorMessage(err)
+      error.value = message
+      throw err
+    } finally {
+      loading.value = false
+    }
+  }
+
+  return {
+    loading,
+    error,
+    fileName,
+    result,
+    importFile,
+    clear,
+  }
+}
+
+export function validateImportFile(file: File, options: FileImportValidationOptions = {}): void {
+  if (options.maxSizeBytes !== undefined && file.size > options.maxSizeBytes) {
+    throw new Error(`File is too large. Maximum size is ${formatBytes(options.maxSizeBytes)}.`)
+  }
+
+  const accept = normalizeAccept(options.accept)
+  if (accept.length === 0) return
+
+  const name = file.name.toLowerCase()
+  const type = file.type.toLowerCase()
+  const matches = accept.some((entry) => {
+    if (entry.startsWith('.')) return name.endsWith(entry)
+    if (entry.endsWith('/*')) return type.startsWith(entry.slice(0, -1))
+    return type === entry
+  })
+
+  if (!matches) {
+    throw new Error(`Unsupported file type. Expected ${accept.join(', ')}.`)
+  }
+}
+
+export function readFileAsText(file: File, encoding?: string): Promise<string> {
+  if (typeof FileReader === 'undefined' && typeof file.text === 'function') {
+    return file.text()
+  }
+
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader()
+    reader.onload = () => resolve(String(reader.result ?? ''))
+    reader.onerror = () => reject(reader.error ?? new Error('Failed to read file.'))
+    reader.readAsText(file, encoding)
+  })
+}
+
+export function parseDelimitedText(
+  text: string,
+  options: ParseDelimitedTextOptions = {},
+): DelimitedTable {
+  const trim = options.trim ?? true
+  const delimiter = options.delimiter ?? detectDelimiter(text)
+  const rawRows = parseDelimitedRows(text, delimiter)
+    .filter(row => row.some(cell => cell.trim().length > 0))
+    .map(row => trim ? row.map(cell => cell.trim()) : row)
+
+  const hasHeaderRow = options.hasHeaderRow ?? !options.headers
+  const columns = options.headers
+    ? [...options.headers]
+    : hasHeaderRow
+      ? rawRows[0] ?? []
+      : createColumnNames(maxRowLength(rawRows))
+
+  const dataRows = hasHeaderRow && !options.headers ? rawRows.slice(1) : rawRows
+  const rows = dataRows.map(row => Object.fromEntries(
+    columns.map((column, index) => [column, row[index] ?? '']),
+  ))
+
+  return {
+    columns,
+    rows,
+    rawRows,
+    delimiter,
+  }
+}
+
+export function detectDelimiter(text: string): string {
+  const firstLine = text.split(/\r?\n/, 1)[0] ?? ''
+  const commaCount = countChar(firstLine, ',')
+  const tabCount = countChar(firstLine, '\t')
+  const semicolonCount = countChar(firstLine, ';')
+  if (tabCount > commaCount && tabCount >= semicolonCount) return '\t'
+  if (semicolonCount > commaCount) return ';'
+  return ','
+}
+
+function parseDelimitedRows(text: string, delimiter: string): string[][] {
+  const rows: string[][] = []
+  let row: string[] = []
+  let field = ''
+  let quoted = false
+
+  for (let index = 0; index < text.length; index++) {
+    const char = text[index]
+    const next = text[index + 1]
+
+    if (char === '"') {
+      if (quoted && next === '"') {
+        field += '"'
+        index++
+      } else {
+        quoted = !quoted
+      }
+      continue
+    }
+
+    if (!quoted && char === delimiter) {
+      row.push(field)
+      field = ''
+      continue
+    }
+
+    if (!quoted && (char === '\n' || char === '\r')) {
+      if (char === '\r' && next === '\n') index++
+      row.push(field)
+      rows.push(row)
+      row = []
+      field = ''
+      continue
+    }
+
+    field += char
+  }
+
+  row.push(field)
+  rows.push(row)
+  return rows
+}
+
+function normalizeAccept(accept: string | readonly string[] | undefined): string[] {
+  if (!accept) return []
+  const entries = typeof accept === 'string' ? accept.split(',') : [...accept]
+  return entries
+    .map((entry: string) => entry.trim().toLowerCase())
+    .filter(Boolean)
+}
+
+function createColumnNames(count: number): string[] {
+  return Array.from({ length: count }, (_, index) => `column_${index + 1}`)
+}
+
+function maxRowLength(rows: readonly string[][]): number {
+  return rows.reduce((max, row) => Math.max(max, row.length), 0)
+}
+
+function countChar(value: string, char: string): number {
+  return [...value].filter(candidate => candidate === char).length
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`
+  return `${Math.round(bytes / (1024 * 1024))} MB`
+}
+
+function readErrorMessage(value: unknown): string {
+  if (value instanceof Error && value.message) return value.message
+  if (typeof value === 'string' && value.trim()) return value
+  return 'Failed to import file.'
+}

package/src/composables/useOptimisticMutation.ts

@@ -0,0 +1,107 @@
+import { computed, ref, shallowRef, type ComputedRef, type Ref, type ShallowRef } from 'vue'
+
+export interface OptimisticMutationContext<TVariables, TSnapshot> {
+  variables: TVariables
+  snapshot: TSnapshot | undefined
+}
+
+export interface UseOptimisticMutationOptions<TVariables, TData, TSnapshot = unknown> {
+  mutation: (variables: TVariables) => Promise<TData>
+  snapshot?: (variables: TVariables) => TSnapshot
+  apply?: (variables: TVariables, snapshot: TSnapshot | undefined) => void
+  commit?: (data: TData, context: OptimisticMutationContext<TVariables, TSnapshot>) => void
+  rollback?: (
+    snapshot: TSnapshot | undefined,
+    variables: TVariables,
+    error: unknown,
+  ) => void
+  onSuccess?: (data: TData, context: OptimisticMutationContext<TVariables, TSnapshot>) => void
+  onError?: (error: unknown, context: OptimisticMutationContext<TVariables, TSnapshot>) => void
+  onSettled?: (context: OptimisticMutationContext<TVariables, TSnapshot>) => void
+  readErrorMessage?: (error: unknown) => string
+}
+
+export interface UseOptimisticMutationReturn<TVariables, TData, TSnapshot = unknown> {
+  loading: ShallowRef<boolean>
+  error: Ref<string | null>
+  data: Ref<TData | null>
+  lastSnapshot: Ref<TSnapshot | undefined>
+  isIdle: ComputedRef<boolean>
+  run: (variables: TVariables) => Promise<TData>
+  clearError: () => void
+  reset: () => void
+}
+
+/** Run async mutations with optional optimistic local updates and rollback. */
+export function useOptimisticMutation<TVariables, TData, TSnapshot = unknown>(
+  options: UseOptimisticMutationOptions<TVariables, TData, TSnapshot>,
+): UseOptimisticMutationReturn<TVariables, TData, TSnapshot> {
+  const loading = shallowRef(false)
+  const error = ref<string | null>(null)
+  const data = ref<TData | null>(null) as Ref<TData | null>
+  const lastSnapshot = ref<TSnapshot | undefined>(undefined) as Ref<TSnapshot | undefined>
+  const isIdle = computed(() => !loading.value && data.value === null && error.value === null)
+
+  function clearError(): void {
+    error.value = null
+  }
+
+  function reset(): void {
+    loading.value = false
+    error.value = null
+    data.value = null
+    lastSnapshot.value = undefined
+  }
+
+  async function run(variables: TVariables): Promise<TData> {
+    const snapshot = options.snapshot?.(variables)
+    const context: OptimisticMutationContext<TVariables, TSnapshot> = { variables, snapshot }
+
+    loading.value = true
+    error.value = null
+    lastSnapshot.value = snapshot
+    options.apply?.(variables, snapshot)
+
+    try {
+      const result = await options.mutation(variables)
+      data.value = result
+      options.commit?.(result, context)
+      options.onSuccess?.(result, context)
+      return result
+    } catch (err) {
+      options.rollback?.(snapshot, variables, err)
+      error.value = options.readErrorMessage?.(err) ?? readErrorMessage(err)
+      options.onError?.(err, context)
+      throw err
+    } finally {
+      loading.value = false
+      options.onSettled?.(context)
+    }
+  }
+
+  return {
+    loading,
+    error,
+    data,
+    lastSnapshot,
+    isIdle,
+    run,
+    clearError,
+    reset,
+  }
+}
+
+function readErrorMessage(value: unknown): string {
+  if (value instanceof Error && value.message) return value.message
+  if (typeof value === 'string' && value.trim()) return value
+  if (
+    typeof value === 'object'
+    && value !== null
+    && 'message' in value
+    && typeof (value as { message?: unknown }).message === 'string'
+    && (value as { message: string }).message.trim()
+  ) {
+    return (value as { message: string }).message
+  }
+  return 'Request failed.'
+}

package/src/composables/useResourceCrud.ts

@@ -0,0 +1,245 @@
+import { computed, ref, shallowRef, type ComputedRef, type Ref, type ShallowRef } from 'vue'
+
+export type ResourceKey = string | number
+
+export interface ResourceCrudAdapter<TItem, TCreate = Partial<TItem>, TUpdate = Partial<TItem>, TKey extends ResourceKey = ResourceKey> {
+  list: () => Promise<TItem[]>
+  create?: (payload: TCreate) => Promise<TItem>
+  update?: (key: TKey, payload: TUpdate) => Promise<TItem>
+  remove?: (key: TKey) => Promise<void>
+}
+
+export interface UseResourceCrudOptions<
+  TItem,
+  TCreate = Partial<TItem>,
+  TUpdate = Partial<TItem>,
+  TKey extends ResourceKey = ResourceKey,
+> {
+  adapter: ResourceCrudAdapter<TItem, TCreate, TUpdate, TKey>
+  initialItems?: readonly TItem[]
+  getKey?: (item: TItem) => TKey
+  readErrorMessage?: (error: unknown) => string
+}
+
+export interface UseResourceCrudReturn<TItem, TCreate, TUpdate, TKey extends ResourceKey> {
+  items: Ref<TItem[]>
+  loading: ShallowRef<boolean>
+  saving: ShallowRef<boolean>
+  deleting: ShallowRef<boolean>
+  error: Ref<string | null>
+  isBusy: ComputedRef<boolean>
+  load: () => Promise<TItem[]>
+  createItem: (payload: TCreate) => Promise<TItem>
+  updateItem: (key: TKey, payload: TUpdate) => Promise<TItem>
+  deleteItem: (keyOrItem: TKey | TItem) => Promise<void>
+  setItems: (items: readonly TItem[]) => void
+  upsertLocal: (item: TItem) => void
+  removeLocal: (keyOrItem: TKey | TItem) => void
+  clearError: () => void
+}
+
+/** Common list/create/update/delete state wrapper for generated plugin clients. */
+export function useResourceCrud<
+  TItem,
+  TCreate = Partial<TItem>,
+  TUpdate = Partial<TItem>,
+  TKey extends ResourceKey = ResourceKey,
+>(
+  options: UseResourceCrudOptions<TItem, TCreate, TUpdate, TKey>,
+): UseResourceCrudReturn<TItem, TCreate, TUpdate, TKey> {
+  const items = ref<TItem[]>([...(options.initialItems ?? [])]) as Ref<TItem[]>
+  const loading = shallowRef(false)
+  const saving = shallowRef(false)
+  const deleting = shallowRef(false)
+  const error = ref<string | null>(null)
+  const isBusy = computed(() => loading.value || saving.value || deleting.value)
+
+  const readMessage = options.readErrorMessage ?? readErrorMessage
+  const getKey = options.getKey ?? defaultGetKey<TKey, TItem>
+
+  function clearError(): void {
+    error.value = null
+  }
+
+  function setError(err: unknown): void {
+    error.value = readMessage(err)
+  }
+
+  function setItems(nextItems: readonly TItem[]): void {
+    items.value = [...nextItems]
+  }
+
+  function upsertLocal(item: TItem): void {
+    const key = getKey(item)
+    const index = items.value.findIndex(existing => getKey(existing) === key)
+    if (index === -1) {
+      items.value = [...items.value, item]
+      return
+    }
+    items.value = [
+      ...items.value.slice(0, index),
+      item,
+      ...items.value.slice(index + 1),
+    ]
+  }
+
+  function removeLocal(keyOrItem: TKey | TItem): void {
+    const key = resolveKey(keyOrItem, getKey)
+    items.value = items.value.filter(item => getKey(item) !== key)
+  }
+
+  async function load(): Promise<TItem[]> {
+    loading.value = true
+    clearError()
+    try {
+      const result = await options.adapter.list()
+      setItems(result)
+      return result
+    } catch (err) {
+      setError(err)
+      throw err
+    } finally {
+      loading.value = false
+    }
+  }
+
+  async function createItem(payload: TCreate): Promise<TItem> {
+    if (!options.adapter.create) {
+      throw new Error('[MINT SDK] Resource adapter does not implement create().')
+    }
+    saving.value = true
+    clearError()
+    try {
+      const result = await options.adapter.create(payload)
+      upsertLocal(result)
+      return result
+    } catch (err) {
+      setError(err)
+      throw err
+    } finally {
+      saving.value = false
+    }
+  }
+
+  async function updateItem(key: TKey, payload: TUpdate): Promise<TItem> {
+    if (!options.adapter.update) {
+      throw new Error('[MINT SDK] Resource adapter does not implement update().')
+    }
+    saving.value = true
+    clearError()
+    try {
+      const result = await options.adapter.update(key, payload)
+      upsertLocal(result)
+      return result
+    } catch (err) {
+      setError(err)
+      throw err
+    } finally {
+      saving.value = false
+    }
+  }
+
+  async function deleteItem(keyOrItem: TKey | TItem): Promise<void> {
+    if (!options.adapter.remove) {
+      throw new Error('[MINT SDK] Resource adapter does not implement remove().')
+    }
+    const key = resolveKey(keyOrItem, getKey)
+    deleting.value = true
+    clearError()
+    try {
+      await options.adapter.remove(key)
+      removeLocal(key)
+    } catch (err) {
+      setError(err)
+      throw err
+    } finally {
+      deleting.value = false
+    }
+  }
+
+  return {
+    items,
+    loading,
+    saving,
+    deleting,
+    error,
+    isBusy,
+    load,
+    createItem,
+    updateItem,
+    deleteItem,
+    setItems,
+    upsertLocal,
+    removeLocal,
+    clearError,
+  }
+}
+
+export interface PluginResourceClientOptions<
+  TClient,
+  TItem,
+  TCreate = Partial<TItem>,
+  TUpdate = Partial<TItem>,
+  TKey extends ResourceKey = ResourceKey,
+> {
+  client: TClient
+  list: (client: TClient) => Promise<TItem[]>
+  create?: (client: TClient, payload: TCreate) => Promise<TItem>
+  update?: (client: TClient, key: TKey, payload: TUpdate) => Promise<TItem>
+  remove?: (client: TClient, key: TKey) => Promise<void>
+}
+
+export function createPluginResourceClient<
+  TClient,
+  TItem,
+  TCreate = Partial<TItem>,
+  TUpdate = Partial<TItem>,
+  TKey extends ResourceKey = ResourceKey,
+>(
+  options: PluginResourceClientOptions<TClient, TItem, TCreate, TUpdate, TKey>,
+): ResourceCrudAdapter<TItem, TCreate, TUpdate, TKey> {
+  return {
+    list: () => options.list(options.client),
+    create: options.create
+      ? payload => options.create!(options.client, payload)
+      : undefined,
+    update: options.update
+      ? (key, payload) => options.update!(options.client, key, payload)
+      : undefined,
+    remove: options.remove
+      ? key => options.remove!(options.client, key)
+      : undefined,
+  }
+}
+
+function defaultGetKey<TKey extends ResourceKey, TItem>(item: TItem): TKey {
+  if (item && typeof item === 'object' && 'id' in item) {
+    return (item as { id: ResourceKey }).id as TKey
+  }
+  throw new Error('[MINT SDK] Resource items need an id field or a getKey option.')
+}
+
+function resolveKey<TItem, TKey extends ResourceKey>(
+  keyOrItem: TKey | TItem,
+  getKey: (item: TItem) => TKey,
+): TKey {
+  if (typeof keyOrItem === 'string' || typeof keyOrItem === 'number') {
+    return keyOrItem as TKey
+  }
+  return getKey(keyOrItem as TItem)
+}
+
+function readErrorMessage(value: unknown): string {
+  if (value instanceof Error && value.message) return value.message
+  if (typeof value === 'string' && value.trim()) return value
+  if (
+    typeof value === 'object'
+    && value !== null
+    && 'message' in value
+    && typeof (value as { message?: unknown }).message === 'string'
+    && (value as { message: string }).message.trim()
+  ) {
+    return (value as { message: string }).message
+  }
+  return 'Request failed.'
+}