@pyreon/feature 0.3.0 → 0.7.0

package/lib/types/index.d.ts

@@ -1,501 +1,259 @@
-import { batch, signal } from "@pyreon/reactivity";
-import { useForm } from "@pyreon/form";
-import { zodSchema } from "@pyreon/validation";
-import { useMutation, useQuery, useQueryClient } from "@pyreon/query";
-import { getCoreRowModel, getFilteredRowModel, getPaginationRowModel, getSortedRowModel, useTable } from "@pyreon/table";
-import { defineStore } from "@pyreon/store";
-
-//#region src/schema.ts
-/** Symbol used to tag reference schema objects. */
+import * as _pyreon_table0 from "@pyreon/table";
+import { SortingState } from "@pyreon/table";
+import { FormState, SchemaValidateFn } from "@pyreon/form";
+import { QueryKey, UseMutationResult, UseQueryResult } from "@pyreon/query";
+import { Computed, Signal } from "@pyreon/reactivity";
+import { StoreApi } from "@pyreon/store";
 
+//#region src/schema.d.ts
 /**
-* Check if a value is a reference schema created by `reference()`.
-*/
-function isReference(value) {
-  return value !== null && typeof value === "object" && value[REFERENCE_TAG] === true;
+ * Schema introspection utilities.
+ *
+ * Extracts field names, types, and metadata from Zod schemas at runtime
+ * without importing Zod types directly (duck-typed).
+ */
+interface FieldInfo {
+  /** Field name (key in the schema object). */
+  name: string;
+  /** Inferred type: 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'array' | 'object' | 'reference' | 'unknown'. */
+  type: FieldType;
+  /** Whether the field is optional. */
+  optional: boolean;
+  /** For enum fields, the list of allowed values. */
+  enumValues?: (string | number)[];
+  /** For reference fields, the name of the referenced feature. */
+  referenceTo?: string;
+  /** Human-readable label derived from field name. */
+  label: string;
 }
+type FieldType = 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'array' | 'object' | 'reference' | 'unknown';
 /**
-* Create a reference field that links to another feature.
-*
-* Returns a Zod-compatible schema that validates as `string | number` and
-* carries metadata about the referenced feature for form dropdowns and table links.
-*
-* @example
-* ```ts
-* import { defineFeature, reference } from '@pyreon/feature'
-*
-* const posts = defineFeature({
-*   name: 'posts',
-*   schema: z.object({
-*     title: z.string(),
-*     authorId: reference(users),
-*   }),
-*   api: '/api/posts',
-* })
-* ```
-*/
-function reference(feature) {
-  const featureName = feature.name;
-  function validateRef(value) {
-    if (typeof value === "string" || typeof value === "number") return {
-      success: true
+ * Metadata carried by a reference schema.
+ */
+interface ReferenceSchema {
+  /** Marker symbol for detection. */
+  [key: symbol]: true;
+  /** Name of the referenced feature. */
+  _featureName: string;
+  /** Duck-typed Zod-like interface: validates as string | number. */
+  safeParse: (value: unknown) => {
+    success: boolean;
+    error?: {
+      issues: {
+        message: string;
+      }[];
     };
-    return {
-      success: false,
-      error: {
-        issues: [{
-          message: `Expected string or number reference to ${featureName}, got ${typeof value}`
-        }]
-      }
+  };
+  /** Async variant for compatibility. */
+  safeParseAsync: (value: unknown) => Promise<{
+    success: boolean;
+    error?: {
+      issues: {
+        message: string;
+      }[];
     };
-  }
-  return {
-    [REFERENCE_TAG]: true,
-    _featureName: featureName,
-    safeParse: validateRef,
-    safeParseAsync: async value => validateRef(value),
-    _def: {
-      typeName: "ZodString"
-    }
+  }>;
+  /** Shape-like marker for schema introspection. */
+  _def: {
+    typeName: string;
   };
 }
 /**
-* Convert a field name to a human-readable label.
-* e.g., 'firstName' → 'First Name', 'created_at' → 'Created At'
-*/
-function nameToLabel(name) {
-  return name.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[_-]/g, " ").replace(/\b\w/g, c => c.toUpperCase());
-}
+ * Check if a value is a reference schema created by `reference()`.
+ */
+declare function isReference(value: unknown): value is ReferenceSchema;
 /**
-* Detect the field type from a Zod schema shape entry.
-* Duck-typed — works with Zod v3 and v4 without importing Zod.
-*/
-function detectFieldType(zodField) {
-  if (isReference(zodField)) return {
-    type: "reference",
-    optional: false,
-    referenceTo: zodField._featureName
-  };
-  if (!zodField || typeof zodField !== "object") return {
-    type: "unknown",
-    optional: false
-  };
-  let inner = zodField;
-  let optional = false;
-  const getTypeName = obj => {
-    const def = obj._def;
-    if (def?.typeName && typeof def.typeName === "string") return def.typeName;
-    const zodDef = obj._zod?.def;
-    if (zodDef?.type && typeof zodDef.type === "string") return zodDef.type;
-  };
-  const typeName = getTypeName(inner);
-  if (typeName === "ZodOptional" || typeName === "ZodNullable" || typeName === "optional" || typeName === "nullable") {
-    optional = true;
-    const innerType = inner._def?.innerType ?? inner._zod?.def;
-    if (innerType && typeof innerType === "object") inner = innerType;
-  }
-  const innerTypeName = getTypeName(inner) ?? typeName;
-  if (!innerTypeName) return {
-    type: "unknown",
-    optional
-  };
-  const type = {
-    ZodString: "string",
-    ZodNumber: "number",
-    ZodBoolean: "boolean",
-    ZodDate: "date",
-    ZodEnum: "enum",
-    ZodNativeEnum: "enum",
-    ZodArray: "array",
-    ZodObject: "object",
-    string: "string",
-    number: "number",
-    boolean: "boolean",
-    date: "date",
-    enum: "enum",
-    array: "array",
-    object: "object"
-  }[innerTypeName] ?? "string";
-  let enumValues;
-  if (type === "enum") {
-    const def = inner._def;
-    if (def?.values && Array.isArray(def.values)) enumValues = def.values;
-    const zodDef = inner._zod?.def;
-    if (zodDef?.values && Array.isArray(zodDef.values)) enumValues = zodDef.values;
-  }
-  return {
-    type,
-    optional,
-    enumValues
-  };
+ * Create a reference field that links to another feature.
+ *
+ * Returns a Zod-compatible schema that validates as `string | number` and
+ * carries metadata about the referenced feature for form dropdowns and table links.
+ *
+ * @example
+ * ```ts
+ * import { defineFeature, reference } from '@pyreon/feature'
+ *
+ * const posts = defineFeature({
+ *   name: 'posts',
+ *   schema: z.object({
+ *     title: z.string(),
+ *     authorId: reference(users),
+ *   }),
+ *   api: '/api/posts',
+ * })
+ * ```
+ */
+declare function reference(feature: {
+  name: string;
+}): ReferenceSchema;
+/**
+ * Extract field information from a Zod object schema.
+ * Returns an array of FieldInfo objects describing each field.
+ *
+ * @example
+ * ```ts
+ * const schema = z.object({ name: z.string(), age: z.number().optional() })
+ * const fields = extractFields(schema)
+ * // [
+ * //   { name: 'name', type: 'string', optional: false, label: 'Name' },
+ * //   { name: 'age', type: 'number', optional: true, label: 'Age' },
+ * // ]
+ * ```
+ */
+declare function extractFields(schema: unknown): FieldInfo[];
+/**
+ * Generate default initial values from a schema's field types.
+ */
+declare function defaultInitialValues(fields: FieldInfo[]): Record<string, unknown>;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Configuration for defining a feature.
+ */
+interface FeatureConfig<TValues extends Record<string, unknown>> {
+  /** Unique feature name — used for store ID and query key namespace. */
+  name: string;
+  /** Validation schema (Zod, Valibot, or ArkType). Duck-typed — must have `safeParseAsync` for auto-validation. */
+  schema: unknown;
+  /** Custom schema-level validation function. If provided, overrides auto-detection from schema. */
+  validate?: SchemaValidateFn<TValues>;
+  /** API base path (e.g., '/api/users'). */
+  api: string;
+  /** Default initial values for create forms. If not provided, auto-generated from schema field types. */
+  initialValues?: Partial<TValues>;
+  /** Custom fetch function. Defaults to global fetch. */
+  fetcher?: typeof fetch;
 }
 /**
-* Extract field information from a Zod object schema.
-* Returns an array of FieldInfo objects describing each field.
-*
-* @example
-* ```ts
-* const schema = z.object({ name: z.string(), age: z.number().optional() })
-* const fields = extractFields(schema)
-* // [
-* //   { name: 'name', type: 'string', optional: false, label: 'Name' },
-* //   { name: 'age', type: 'number', optional: true, label: 'Age' },
-* // ]
-* ```
-*/
-function extractFields(schema) {
-  if (!schema || typeof schema !== "object") return [];
-  const s = schema;
-  let shape;
-  if (s.shape && typeof s.shape === "object") shape = s.shape;
-  if (!shape) {
-    const def = s._def;
-    if (def?.shape) shape = typeof def.shape === "function" ? def.shape() : def.shape;
-  }
-  if (!shape) {
-    const zodDef = s._zod?.def;
-    if (zodDef?.shape && typeof zodDef.shape === "object") shape = zodDef.shape;
-  }
-  if (!shape) return [];
-  return Object.entries(shape).map(([name, fieldSchema]) => {
-    const {
-      type,
-      optional,
-      enumValues,
-      referenceTo
-    } = detectFieldType(fieldSchema);
-    const info = {
-      name,
-      type,
-      optional,
-      label: nameToLabel(name)
-    };
-    if (enumValues) info.enumValues = enumValues;
-    if (referenceTo) info.referenceTo = referenceTo;
-    return info;
-  });
+ * Query options for useList.
+ */
+interface ListOptions {
+  /** Additional query parameters appended to the URL. */
+  params?: Record<string, string | number | boolean>;
+  /** Reactive page number. When provided, `page` and `pageSize` are appended to query params. */
+  page?: number | Signal<number>;
+  /** Items per page. Defaults to 20 when `page` is provided. */
+  pageSize?: number;
+  /** Override stale time for this query. */
+  staleTime?: number;
+  /** Enable/disable the query. */
+  enabled?: boolean;
 }
 /**
-* Generate default initial values from a schema's field types.
-*/
-function defaultInitialValues(fields) {
-  const values = {};
-  for (const field of fields) switch (field.type) {
-    case "string":
-      values[field.name] = "";
-      break;
-    case "number":
-      values[field.name] = 0;
-      break;
-    case "boolean":
-      values[field.name] = false;
-      break;
-    case "enum":
-      values[field.name] = field.enumValues?.[0] ?? "";
-      break;
-    case "date":
-      values[field.name] = "";
-      break;
-    default:
-      values[field.name] = "";
-  }
-  return values;
+ * Form options for useForm.
+ */
+interface FeatureFormOptions<TValues extends Record<string, unknown>> {
+  /** 'create' (default) or 'edit'. Edit mode uses PUT instead of POST. */
+  mode?: 'create' | 'edit';
+  /** Item ID — required when mode is 'edit'. Used to PUT to api/:id and auto-fetch data. */
+  id?: string | number;
+  /** Override initial values (merged with feature defaults). */
+  initialValues?: Partial<TValues>;
+  /** When to validate: 'blur' (default), 'change', or 'submit'. */
+  validateOn?: 'blur' | 'change' | 'submit';
+  /** Callback after successful create/update. */
+  onSuccess?: (result: unknown) => void;
+  /** Callback on submit error. */
+  onError?: (error: unknown) => void;
 }
-
-//#endregion
-//#region src/define-feature.ts
-function createFetcher(baseFetcher = fetch) {
-  async function request(url, init) {
-    const res = await baseFetcher(url, init);
-    if (!res.ok) {
-      let message = `${init?.method ?? "GET"} ${url} failed: ${res.status}`;
-      try {
-        const body = await res.json();
-        if (body?.message) message = body.message;
-        if (body?.errors) throw Object.assign(new Error(message), {
-          status: res.status,
-          errors: body.errors
-        });
-      } catch (e) {
-        if (e instanceof Error && "errors" in e) throw e;
-      }
-      throw Object.assign(new Error(message), {
-        status: res.status
-      });
-    }
-    if (res.status === 204) return void 0;
-    return res.json();
-  }
-  return {
-    list(url, params) {
-      return request(`${url}${params ? `?${new URLSearchParams(Object.entries(params).map(([k, v]) => [k, String(v)])).toString()}` : ""}`);
-    },
-    getById(url, id) {
-      return request(`${url}/${id}`);
-    },
-    create(url, data) {
-      return request(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify(data)
-      });
-    },
-    update(url, id, data) {
-      return request(`${url}/${id}`, {
-        method: "PUT",
-        headers: {
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify(data)
-      });
-    },
-    delete(url, id) {
-      return request(`${url}/${id}`, {
-        method: "DELETE"
-      });
-    }
-  };
+/**
+ * Table options for useTable.
+ */
+interface FeatureTableOptions<TValues extends Record<string, unknown>> {
+  /** Subset of schema fields to show as columns. If not provided, all fields are shown. */
+  columns?: (keyof TValues & string)[];
+  /** Per-column overrides (header text, cell renderer, size, etc.). */
+  columnOverrides?: Partial<Record<keyof TValues & string, Record<string, unknown>>>;
+  /** Page size for pagination. If not provided, pagination is disabled. */
+  pageSize?: number;
 }
-function createValidator(schema, customValidate) {
-  if (customValidate) return customValidate;
-  if (schema && typeof schema === "object" && "safeParseAsync" in schema && typeof schema.safeParseAsync === "function") return zodSchema(schema);
+/**
+ * Return type of feature.useTable().
+ */
+interface FeatureTableResult<TValues extends Record<string, unknown>> {
+  /** The reactive TanStack Table instance. */
+  table: Computed<_pyreon_table0.Table<TValues>>;
+  /** Sorting state signal — bind to UI controls. */
+  sorting: Signal<SortingState>;
+  /** Global filter signal — bind to search input. */
+  globalFilter: Signal<string>;
+  /** Column metadata from schema introspection. */
+  columns: FieldInfo[];
 }
-function resolvePageValue(page) {
-  if (page === void 0) return void 0;
-  if (typeof page === "function") return page();
-  return page;
+/**
+ * Reactive store for a feature's cached data.
+ */
+interface FeatureStore<TValues extends Record<string, unknown>> {
+  /** Cached list of items. */
+  items: Signal<TValues[]>;
+  /** Currently selected item. */
+  selected: Signal<TValues | null>;
+  /** Loading state. */
+  loading: Signal<boolean>;
+  /** Set the selected item by ID (finds from items list). */
+  select: (id: string | number) => void;
+  /** Clear the current selection. */
+  clear: () => void;
+  /** Index signature for Record<string, unknown> compatibility. */
+  [key: string]: unknown;
 }
 /**
-* Define a schema-driven feature with auto-generated CRUD hooks.
-*
-* @example
-* ```ts
-* import { defineFeature } from '@pyreon/feature'
-* import { z } from 'zod'
-*
-* const users = defineFeature({
-*   name: 'users',
-*   schema: z.object({
-*     name: z.string().min(2),
-*     email: z.string().email(),
-*     role: z.enum(['admin', 'editor', 'viewer']),
-*   }),
-*   api: '/api/users',
-* })
-* ```
-*/
-function defineFeature(config) {
-  const {
-    name,
-    schema,
-    api,
-    fetcher: customFetcher
-  } = config;
-  const http = createFetcher(customFetcher);
-  const fields = extractFields(schema);
-  const autoInitialValues = defaultInitialValues(fields);
-  const initialValues = config.initialValues ? {
-    ...autoInitialValues,
-    ...config.initialValues
-  } : autoInitialValues;
-  const validate = createValidator(schema, config.validate);
-  const queryKeyBase = [name];
-  const queryKey = suffix => suffix !== void 0 ? [name, suffix] : [name];
-  return {
-    name,
-    api,
-    schema,
-    fields,
-    queryKey,
-    useStore: defineStore(name, () => {
-      const items = signal([]);
-      const selected = signal(null);
-      const loading = signal(false);
-      const select = id => {
-        const found = items.peek().find(item => {
-          return item.id === id;
-        });
-        selected.set(found ?? null);
-      };
-      const clear = () => {
-        selected.set(null);
-      };
-      return {
-        items,
-        selected,
-        loading,
-        select,
-        clear
-      };
-    }),
-    useList(options) {
-      return useQuery(() => {
-        const pageValue = resolvePageValue(options?.page);
-        const pageSize = options?.pageSize ?? 20;
-        const params = {
-          ...(options?.params ?? {})
-        };
-        if (pageValue !== void 0) {
-          params.page = pageValue;
-          params.pageSize = pageSize;
-        }
-        return {
-          queryKey: [...queryKeyBase, "list", params],
-          queryFn: () => http.list(api, Object.keys(params).length > 0 ? params : void 0),
-          staleTime: options?.staleTime,
-          enabled: options?.enabled
-        };
-      });
-    },
-    useById(id) {
-      return useQuery(() => ({
-        queryKey: [name, id],
-        queryFn: () => http.getById(api, id),
-        enabled: id !== void 0 && id !== null
-      }));
-    },
-    useSearch(searchTerm, options) {
-      return useQuery(() => ({
-        queryKey: [...queryKeyBase, "search", searchTerm()],
-        queryFn: () => http.list(api, {
-          ...options?.params,
-          q: searchTerm()
-        }),
-        enabled: searchTerm().length > 0,
-        staleTime: options?.staleTime
-      }));
-    },
-    useCreate() {
-      const client = useQueryClient();
-      return useMutation({
-        mutationFn: data => http.create(api, data),
-        onSuccess: () => {
-          client.invalidateQueries({
-            queryKey: queryKeyBase
-          });
-        }
-      });
-    },
-    useUpdate() {
-      const client = useQueryClient();
-      return useMutation({
-        mutationFn: ({
-          id,
-          data
-        }) => http.update(api, id, data),
-        onMutate: async variables => {
-          await client.cancelQueries({
-            queryKey: [name, variables.id]
-          });
-          const previous = client.getQueryData([name, variables.id]);
-          client.setQueryData([name, variables.id], old => {
-            if (old && typeof old === "object") return {
-              ...old,
-              ...variables.data
-            };
-            return variables.data;
-          });
-          return {
-            previous
-          };
-        },
-        onError: (_err, variables, context) => {
-          if (context?.previous) client.setQueryData([name, variables.id], context.previous);
-        },
-        onSuccess: (_data, variables) => {
-          client.invalidateQueries({
-            queryKey: queryKeyBase
-          });
-          client.invalidateQueries({
-            queryKey: [name, variables.id]
-          });
-        }
-      });
-    },
-    useDelete() {
-      const client = useQueryClient();
-      return useMutation({
-        mutationFn: id => http.delete(api, id),
-        onSuccess: () => {
-          client.invalidateQueries({
-            queryKey: queryKeyBase
-          });
-        }
-      });
-    },
-    useForm(options) {
-      const mode = options?.mode ?? "create";
-      const form = useForm({
-        initialValues: {
-          ...initialValues,
-          ...(options?.initialValues ?? {})
-        },
-        schema: validate,
-        validateOn: options?.validateOn ?? "blur",
-        onSubmit: async values => {
-          try {
-            let result;
-            if (mode === "edit" && options?.id !== void 0) result = await http.update(api, options.id, values);else result = await http.create(api, values);
-            options?.onSuccess?.(result);
-          } catch (err) {
-            options?.onError?.(err);
-            throw err;
-          }
-        }
-      });
-      if (mode === "edit" && options?.id !== void 0) {
-        form.isSubmitting.set(true);
-        http.getById(api, options.id).then(data => {
-          batch(() => {
-            for (const key of Object.keys(data)) form.setFieldValue(key, data[key]);
-            form.isSubmitting.set(false);
-          });
-        }, () => {
-          form.isSubmitting.set(false);
-        });
-      }
-      return form;
-    },
-    useTable(data, options) {
-      const visibleFields = options?.columns ? fields.filter(f => options.columns.includes(f.name)) : fields;
-      const columns = visibleFields.map(field => ({
-        accessorKey: field.name,
-        header: field.label,
-        ...(options?.columnOverrides?.[field.name] ?? {})
-      }));
-      const sorting = signal([]);
-      const globalFilter = signal("");
-      return {
-        table: useTable(() => ({
-          data: typeof data === "function" ? data() : data,
-          columns,
-          state: {
-            sorting: sorting(),
-            globalFilter: globalFilter()
-          },
-          onSortingChange: updater => {
-            sorting.set(typeof updater === "function" ? updater(sorting()) : updater);
-          },
-          onGlobalFilterChange: updater => {
-            globalFilter.set(typeof updater === "function" ? updater(globalFilter()) : updater);
-          },
-          getCoreRowModel: getCoreRowModel(),
-          getSortedRowModel: getSortedRowModel(),
-          getFilteredRowModel: getFilteredRowModel(),
-          ...(options?.pageSize ? {
-            getPaginationRowModel: getPaginationRowModel()
-          } : {})
-        })),
-        sorting,
-        globalFilter,
-        columns: visibleFields
-      };
-    }
-  };
+ * The feature object returned by defineFeature().
+ */
+interface Feature<TValues extends Record<string, unknown>> {
+  /** Feature name. */
+  name: string;
+  /** API base path. */
+  api: string;
+  /** The schema passed to defineFeature. */
+  schema: unknown;
+  /** Introspected field information from the schema. */
+  fields: FieldInfo[];
+  /** Fetch a paginated/filtered list. */
+  useList: (options?: ListOptions) => UseQueryResult<TValues[], unknown>;
+  /** Fetch a single item by ID. */
+  useById: (id: string | number) => UseQueryResult<TValues, unknown>;
+  /** Search with a reactive signal term. */
+  useSearch: (searchTerm: Signal<string>, options?: ListOptions) => UseQueryResult<TValues[], unknown>;
+  /** Create mutation — POST to api. */
+  useCreate: () => UseMutationResult<TValues, unknown, Partial<TValues>>;
+  /** Update mutation — PUT to api/:id with optimistic updates. */
+  useUpdate: () => UseMutationResult<TValues, unknown, {
+    id: string | number;
+    data: Partial<TValues>;
+  }>;
+  /** Delete mutation — DELETE to api/:id. */
+  useDelete: () => UseMutationResult<void, unknown, string | number>;
+  /** Create a form pre-wired with schema validation and API submit. In edit mode with an ID, auto-fetches data. */
+  useForm: (options?: FeatureFormOptions<TValues>) => FormState<TValues>;
+  /** Create a reactive table with columns inferred from schema. */
+  useTable: (data: TValues[] | (() => TValues[]), options?: FeatureTableOptions<TValues>) => FeatureTableResult<TValues>;
+  /** Reactive store for cached items, selection, and loading state. */
+  useStore: () => StoreApi<FeatureStore<TValues>>;
+  /** Generate namespaced query keys. */
+  queryKey: (suffix?: string | number) => QueryKey;
 }
-
 //#endregion
-export { defaultInitialValues, defineFeature, extractFields, isReference, reference };
-//# sourceMappingURL=index.d.ts.map
+//#region src/define-feature.d.ts
+/**
+ * Define a schema-driven feature with auto-generated CRUD hooks.
+ *
+ * @example
+ * ```ts
+ * import { defineFeature } from '@pyreon/feature'
+ * import { z } from 'zod'
+ *
+ * const users = defineFeature({
+ *   name: 'users',
+ *   schema: z.object({
+ *     name: z.string().min(2),
+ *     email: z.string().email(),
+ *     role: z.enum(['admin', 'editor', 'viewer']),
+ *   }),
+ *   api: '/api/users',
+ * })
+ * ```
+ */
+declare function defineFeature<TValues extends Record<string, unknown>>(config: FeatureConfig<TValues>): Feature<TValues>;
+//#endregion
+export { type Feature, type FeatureConfig, type FeatureFormOptions, type FeatureStore, type FeatureTableOptions, type FeatureTableResult, type FieldInfo, type FieldType, type ListOptions, type ReferenceSchema, defaultInitialValues, defineFeature, extractFields, isReference, reference };
+//# sourceMappingURL=index2.d.ts.map