@padosoft/utilities 1.4.0

package/dist/index.d.mts

@@ -0,0 +1,7 @@
+import { ConfigOverride, Configuration, defineConfigOverride } from "./lib/configuration.mjs";
+import { fillArray, isColor, sleep, toPascalCase } from "./lib/utils.mjs";
+import { QueryDefinition, QueryDescriptor, defineQuery, defineQueryGroup } from "./lib/query.mjs";
+import { QueryProxy, createQueryProxy } from "./lib/query-proxy.mjs";
+import { DeepMutable, DeepPartial, FullPartial, Intersect, LiteralUnion, MergeWithDefault, Mutable, Prettify, Satisfies } from "./types/utils.mjs";
+import { ConvertMaybeZod, DeepConvertMaybeZod } from "./types/zod.mjs";
+export { ConfigOverride, Configuration, ConvertMaybeZod, DeepConvertMaybeZod, DeepMutable, DeepPartial, FullPartial, Intersect, LiteralUnion, MergeWithDefault, Mutable, Prettify, QueryDefinition, QueryDescriptor, QueryProxy, Satisfies, createQueryProxy, defineConfigOverride, defineQuery, defineQueryGroup, fillArray, isColor, sleep, toPascalCase };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{Configuration as e,defineConfigOverride as t}from"./lib/configuration.mjs";import{fillArray as n,isColor as r,sleep as i,toPascalCase as a}from"./lib/utils.mjs";import{defineQuery as o,defineQueryGroup as s}from"./lib/query.mjs";import{createQueryProxy as c}from"./lib/query-proxy.mjs";export{e as Configuration,c as createQueryProxy,t as defineConfigOverride,o as defineQuery,s as defineQueryGroup,n as fillArray,r as isColor,i as sleep,a as toPascalCase};

package/dist/lib/configuration.d.mts

@@ -0,0 +1,22 @@
+//#region src/lib/configuration.d.ts
+interface ConfigOverride<TConfig extends object, K extends keyof TConfig = keyof TConfig> {
+  key: K;
+  override: (config: Readonly<TConfig>) => TConfig[K];
+}
+declare function defineConfigOverride<TConfig extends object, K extends keyof TConfig>(key: K, override: ConfigOverride<TConfig, K>["override"]): ConfigOverride<TConfig, K>;
+declare class Configuration<TConfig extends object> {
+  protected overrides: ConfigOverride<TConfig>[];
+  protected config: TConfig;
+  private listeners;
+  constructor(defaultConfig: TConfig);
+  protected applyOverrides(config: TConfig): TConfig;
+  addOverride<K extends keyof TConfig>(override: ConfigOverride<TConfig, K>): void;
+  set(config: TConfig): void;
+  subscribe(listener: () => void): (() => void);
+  getSnapshot(): TConfig;
+  get(): TConfig;
+  get<K extends keyof TConfig>(key: K): TConfig[K];
+  get<K extends keyof TConfig>(key: K, defaultValue: NonNullable<TConfig[K]>): NonNullable<TConfig[K]>;
+}
+//#endregion
+export { ConfigOverride, Configuration, defineConfigOverride };

package/dist/lib/configuration.mjs

@@ -0,0 +1 @@
+function e(e,t){return{key:e,override:t}}var t=class{overrides=[];config;listeners=new Set;constructor(e){this.config=e}applyOverrides(e){let t={...e};for(let e of this.overrides)t={...t,[e.key]:e.override(t)};return t}addOverride(e){this.overrides.push(e)}set(e){this.config=this.applyOverrides(e);for(let e of this.listeners)e()}subscribe(e){return this.listeners.add(e),()=>this.listeners.delete(e)}getSnapshot(){return this.config}get(e,t){return e?this.config[e]??t:this.config}};export{t as Configuration,e as defineConfigOverride};

package/dist/lib/index.d.mts

@@ -0,0 +1,5 @@
+import { ConfigOverride, Configuration, defineConfigOverride } from "./configuration.mjs";
+import { fillArray, isColor, sleep, toPascalCase } from "./utils.mjs";
+import { QueryDefinition, QueryDescriptor, defineQuery, defineQueryGroup } from "./query.mjs";
+import { QueryProxy, createQueryProxy } from "./query-proxy.mjs";
+export { ConfigOverride, Configuration, QueryDefinition, QueryDescriptor, QueryProxy, createQueryProxy, defineConfigOverride, defineQuery, defineQueryGroup, fillArray, isColor, sleep, toPascalCase };

package/dist/lib/index.mjs

@@ -0,0 +1 @@
+import{Configuration as e,defineConfigOverride as t}from"./configuration.mjs";import{fillArray as n,isColor as r,sleep as i,toPascalCase as a}from"./utils.mjs";import{defineQuery as o,defineQueryGroup as s}from"./query.mjs";import{createQueryProxy as c}from"./query-proxy.mjs";export{e as Configuration,c as createQueryProxy,t as defineConfigOverride,o as defineQuery,s as defineQueryGroup,n as fillArray,r as isColor,i as sleep,a as toPascalCase};

package/dist/lib/query-proxy.d.mts

@@ -0,0 +1,61 @@
+import { QueryDescriptor } from "./query.mjs";
+
+//#region src/lib/query-proxy.d.ts
+/**
+* An async method augmented with `$key` and `$query` helpers.
+* The function itself remains directly callable.
+*/
+type QueryLeaf<TArgs extends unknown[], TResult> = {
+  (...args: TArgs): Promise<TResult>; /** Returns the query key array for the given arguments. */
+  $key(...args: TArgs): readonly unknown[]; /** Returns `{ queryKey, queryFn }` — spread directly into `useQuery()`. */
+  $query(...args: TArgs): QueryDescriptor<TResult>;
+};
+/**
+* Recursively transforms a typed object:
+* - Promise-returning methods → `QueryLeaf` (augmented with `$key` + `$query`)
+* - Synchronous functions → passed through unchanged
+* - Nested objects → recursively transformed
+* - Primitives → passed through unchanged
+*/
+type QueryProxy<T> = T extends ((...args: infer A) => Promise<infer R>) ? QueryLeaf<A, R> : T extends ((...args: infer A) => infer R) ? (...args: A) => R : T extends object ? { readonly [K in keyof T]: QueryProxy<T[K]> } : T;
+/**
+* Wraps any typed object in a proxy that augments every async method with
+* `.$key(...args)` and `.$query(...args)` helpers.
+*
+* The query key is derived automatically from the property-access path through
+* the object plus the call arguments — no separate key definitions needed.
+*
+* Works with any typed object: REST clients, tRPC, service classes, etc.
+*
+* @example
+* ```ts
+* const q = createQueryProxy(apiClient);
+*
+* // Key — path through the object + args, no manual definition:
+* q.v1.auth.getSession.$key(params)
+* // → ['v1', 'auth', 'getSession', params]
+*
+* // Spread into useQuery — params specified exactly once:
+* useQuery({
+*   ...q.v1.auth.getSession.$query(params),
+*   enabled: !!user,
+* });
+*
+* // Direct call still works identically:
+* await q.v1.auth.getSession(params);
+*
+* // For hook-based clients, wrap in useMemo:
+* function useQ() {
+*   const client = useApiClient();
+*   return useMemo(() => createQueryProxy(client), [client]);
+* }
+* ```
+*
+* @param target - Any typed object with async methods.
+* @param options.baseKey - Optional prefix prepended to every generated key.
+*/
+declare function createQueryProxy<T extends object>(target: T, options?: {
+  baseKey?: readonly unknown[];
+}): QueryProxy<T>;
+//#endregion
+export { QueryProxy, createQueryProxy };

package/dist/lib/query-proxy.mjs

@@ -0,0 +1 @@
+function e(e,n){return t(e,[],n?.baseKey??[])}function t(e,n,r){return new Proxy(e,{get(e,i){if(typeof i==`symbol`)return e[i];let a=e[i],o=[...n,i];if(typeof a==`function`){let t=a.bind(e);return Object.assign((...e)=>t(...e),{$key:(...e)=>[...r,...o,...e],$query:(...e)=>({queryKey:[...r,...o,...e],queryFn:()=>t(...e)})})}return typeof a==`object`&&a?t(a,o,r):a}})}export{e as createQueryProxy};

package/dist/lib/query.d.mts

@@ -0,0 +1,83 @@
+//#region src/lib/query.d.ts
+/**
+* A plain object compatible with React Query (and similar libs) without importing them.
+* Spread directly into `useQuery()`, `useSuspenseQuery()`, etc.
+*/
+type QueryDescriptor<TResult> = {
+  queryKey: readonly unknown[];
+  queryFn: () => Promise<TResult>;
+};
+/**
+* A typed query definition — holds the key factory and the fn factory together
+* so parameters only need to be specified once at the call site.
+*/
+type QueryDefinition<TParams, TResult> = {
+  /** Returns the query key array for the given params. Use for cache invalidation / prefetching. */key(params: TParams): readonly unknown[]; /** Returns `{ queryKey, queryFn }` — spread directly into `useQuery()`. */
+  query(params: TParams): QueryDescriptor<TResult>;
+};
+/**
+* Defines a typed query that pairs a key factory with a fn factory sharing the same params.
+*
+* The returned object is framework-agnostic — `query(params)` produces a plain
+* `{ queryKey, queryFn }` object that can be spread into any React Query compatible hook.
+*
+* @example
+* ```ts
+* const cmsSectionQuery = defineQuery({
+*   queryKey: (p) => ['cms', 'section', p],
+*   queryFn: (p) => api.v1.cms.getCmsSection(p.section, p),
+* });
+*
+* // In component — params specified once:
+* useQuery({
+*   ...cmsSectionQuery.query({ section, nazioni_ID, listini_ID, lang, device }),
+*   enabled: !!section,
+* });
+*
+* // For cache invalidation:
+* queryClient.invalidateQueries({ queryKey: cmsSectionQuery.key({ section, ... }) });
+* ```
+*/
+declare function defineQuery<TParams, TResult>(config: {
+  queryKey: (params: TParams) => readonly unknown[];
+  queryFn: (params: TParams) => Promise<TResult>;
+}): QueryDefinition<TParams, TResult>;
+/**
+* Groups related query definitions under a shared base key.
+*
+* Each member query's key is automatically prefixed with `baseKey`,
+* so individual queries only define their tail segment.
+* `group.base()` returns the raw base key for blanket invalidation.
+*
+* @example
+* ```ts
+* const pagesQueries = defineQueryGroup({
+*   baseKey: ['pages'],
+*   queries: {
+*     single: defineQuery({
+*       queryKey: ({ id, nazioni_ID }) => ['single', { id, nazioni_ID }],
+*       queryFn: ({ id, nazioni_ID }) => api.v1.cms.getPage(id, { nazioni_ID }),
+*     }),
+*     list: defineQuery({
+*       queryKey: ({ ids, nazioni_ID }) => ['list', { ids, nazioni_ID }],
+*       queryFn: (params) => api.v1.cms.getPages(params),
+*     }),
+*   },
+* });
+*
+* pagesQueries.base()                    // → ['pages']
+* pagesQueries.single.key({ id: 1, ... }) // → ['pages', 'single', { id: 1, ... }]
+* pagesQueries.single.query({ id: 1, ... }) // → { queryKey, queryFn }
+*
+* // Invalidate all pages at once:
+* queryClient.invalidateQueries({ queryKey: pagesQueries.base() });
+* ```
+*/
+declare function defineQueryGroup<TBase extends readonly unknown[], TDefs extends Record<string, QueryDefinition<unknown, unknown>>>(config: {
+  baseKey: TBase;
+  queries: TDefs;
+}): {
+  base(): TBase;
+} & TDefs;
+//#endregion
+export { QueryDefinition, QueryDescriptor, defineQuery, defineQueryGroup };

package/dist/lib/query.mjs

@@ -0,0 +1 @@
+function e(e){return{key:e.queryKey,query:t=>({queryKey:e.queryKey(t),queryFn:()=>e.queryFn(t)})}}function t(e){let t={base:()=>e.baseKey};for(let[n,r]of Object.entries(e.queries))t[n]={key:t=>[...e.baseKey,...r.key(t)],query:t=>{let n=r.query(t);return{queryKey:[...e.baseKey,...n.queryKey],queryFn:n.queryFn}}};return t}export{e as defineQuery,t as defineQueryGroup};

package/dist/lib/turbo.d.mts

@@ -0,0 +1,6 @@
+//#region src/lib/turbo.d.ts
+declare const listApps: () => string[];
+declare const listPacakges: () => string[];
+declare const fileNameValidator: (input: string) => string | boolean;
+//#endregion
+export { fileNameValidator, listApps, listPacakges };

package/dist/lib/turbo.mjs

@@ -0,0 +1 @@
+import{readdirSync as e}from"node:fs";import{resolve as t}from"node:path";import{cwd as n}from"node:process";const r=()=>e(t(n(),`apps`)),i=()=>e(t(n(),`packages`)),a=e=>e.includes(`.`)?`file name cannot include an extension`:e.includes(` `)?`file name cannot include spaces`:e?!0:`file name is required`;export{a as fileNameValidator,r as listApps,i as listPacakges};

package/dist/lib/utils.d.mts

@@ -0,0 +1,7 @@
+//#region src/lib/utils.d.ts
+declare const fillArray: <T>(obj: T, n?: number) => T[];
+declare const toPascalCase: (string: string) => string;
+declare const isColor: (str: string) => boolean;
+declare const sleep: (ms?: number) => Promise<void>;
+//#endregion
+export { fillArray, isColor, sleep, toPascalCase };

package/dist/lib/utils.mjs

@@ -0,0 +1 @@
+const e=(e,t=8)=>Array.from({length:t},()=>({...e})),t=e=>{"worklet";return`${e}`.toLowerCase().replace(new RegExp(/[-_]+/,`g`),` `).replace(new RegExp(/[^\w\s]/,`g`),``).replace(new RegExp(/\s+(.)(\w*)/,`g`),(e,t,n)=>`${t.toUpperCase()+n}`).replace(new RegExp(/\w/),e=>e.toUpperCase())},n=e=>/^#([0-9A-Fa-f]{3}){1,2}$|^rgb/.test(e),r=(e=5e3)=>new Promise(t=>setTimeout(()=>t(),e));export{e as fillArray,n as isColor,r as sleep,t as toPascalCase};

package/dist/lib/zod/codecs/index.d.mts

@@ -0,0 +1,2 @@
+import { jsonCodec } from "./json.mjs";
+export { jsonCodec };

package/dist/lib/zod/codecs/index.mjs

@@ -0,0 +1 @@
+import{jsonCodec as e}from"./json.mjs";export{e as jsonCodec};

package/dist/lib/zod/codecs/json.d.mts

@@ -0,0 +1,6 @@
+import z from "zod";
+
+//#region src/lib/zod/codecs/json.d.ts
+declare const jsonCodec: <T extends z.core.$ZodType>(schema: T) => z.ZodCodec<z.ZodString, T>;
+//#endregion
+export { jsonCodec };

package/dist/lib/zod/codecs/json.mjs

@@ -0,0 +1 @@
+import e from"zod";const t=t=>e.codec(e.string(),t,{decode:(t,n)=>{try{return JSON.parse(t)}catch(r){let i=r instanceof Error?r.message:String(r);return n.issues.push({code:`invalid_format`,format:`json`,input:t,message:i}),e.NEVER}},encode:e=>JSON.stringify(e)});export{t as jsonCodec};

package/dist/lib/zod/index.d.mts

@@ -0,0 +1,3 @@
+import { jsonCodec } from "./codecs/json.mjs";
+import { FormattedZodError, formatZodError } from "./utils.mjs";
+export { FormattedZodError, formatZodError, jsonCodec };

package/dist/lib/zod/index.mjs

@@ -0,0 +1 @@
+import{jsonCodec as e}from"./codecs/json.mjs";import"./codecs/index.mjs";import{formatZodError as t}from"./utils.mjs";export{t as formatZodError,e as jsonCodec};

package/dist/lib/zod/utils.d.mts

@@ -0,0 +1,10 @@
+import * as z from "zod/v4/core";
+
+//#region src/lib/zod/utils.d.ts
+interface FormattedZodError {
+  code: string;
+  message: string;
+}
+declare const formatZodError: (error: z.$ZodError) => Readonly<FormattedZodError>;
+//#endregion
+export { FormattedZodError, formatZodError };

package/dist/lib/zod/utils.mjs

@@ -0,0 +1 @@
+import{prettifyError as e}from"zod/v4/core";const t=t=>{let n=t.issues[0];return n?{code:n.code.toUpperCase(),message:e(t)}:{code:`UNKNOWN`,message:`Unknown issue`}};export{t as formatZodError};

package/dist/types/index.d.mts

@@ -0,0 +1,3 @@
+import { DeepMutable, DeepPartial, FullPartial, Intersect, LiteralUnion, MergeWithDefault, Mutable, Prettify, Satisfies } from "./utils.mjs";
+import { ConvertMaybeZod, DeepConvertMaybeZod } from "./zod.mjs";
+export { ConvertMaybeZod, DeepConvertMaybeZod, DeepMutable, DeepPartial, FullPartial, Intersect, LiteralUnion, MergeWithDefault, Mutable, Prettify, Satisfies };

package/dist/types/index.mjs

@@ -0,0 +1 @@
+export{};

package/dist/types/utils.d.mts

@@ -0,0 +1,12 @@
+//#region src/types/utils.d.ts
+type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T;
+type FullPartial<T> = T extends object ? { [P in keyof T]?: T[P] | undefined } : T;
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+type Intersect<T> = (T extends unknown ? (x: T) => 0 : never) extends ((x: infer R) => 0) ? R : never;
+type MergeWithDefault<T extends Record<string, unknown>, Key extends string, Value> = Key extends keyof T ? T : T & { [K in Key]: Value };
+type Satisfies<U, T extends U> = T;
+type LiteralUnion<T extends U, U = string> = T | (U & {});
+type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+type DeepMutable<T> = T extends object ? { [P in keyof T]: DeepMutable<T[P]> } : T;
+//#endregion
+export { DeepMutable, DeepPartial, FullPartial, Intersect, LiteralUnion, MergeWithDefault, Mutable, Prettify, Satisfies };

package/dist/types/utils.mjs

@@ -0,0 +1 @@
+export{};

package/dist/types/zod.d.mts

@@ -0,0 +1,7 @@
+import * as z from "zod/v4/core";
+
+//#region src/types/zod.d.ts
+type ConvertMaybeZod<T> = T extends z.$ZodType ? z.infer<T> : T;
+type DeepConvertMaybeZod<T> = T extends z.$ZodType ? z.infer<T> : T extends Array<infer U> ? DeepConvertMaybeZod<U>[] : T extends ReadonlyArray<infer U> ? Readonly<DeepConvertMaybeZod<U>>[] : T extends object ? { [K in keyof T]: DeepConvertMaybeZod<T[K]> } : T;
+//#endregion
+export { ConvertMaybeZod, DeepConvertMaybeZod };

package/dist/types/zod.mjs

@@ -0,0 +1 @@
+export{};

package/package.json

@@ -0,0 +1,86 @@
+{
+	"name": "@padosoft/utilities",
+	"version": "1.4.0",
+	"type": "module",
+	"types": "./dist/index.d.mts",
+	"exports": {
+		".": {
+			"default": "./dist/index.mjs",
+			"types": "./dist/index.d.mts"
+		},
+		"./lib": {
+			"default": "./dist/lib/index.mjs",
+			"types": "./dist/lib/index.d.mts"
+		},
+		"./lib/configuration": {
+			"default": "./dist/lib/configuration.mjs",
+			"types": "./dist/lib/configuration.d.mts"
+		},
+		"./lib/query": {
+			"default": "./dist/lib/query.mjs",
+			"types": "./dist/lib/query.d.mts"
+		},
+		"./lib/query-proxy": {
+			"default": "./dist/lib/query-proxy.mjs",
+			"types": "./dist/lib/query-proxy.d.mts"
+		},
+		"./lib/turbo": {
+			"default": "./dist/lib/turbo.mjs",
+			"types": "./dist/lib/turbo.d.mts"
+		},
+		"./lib/utils": {
+			"default": "./dist/lib/utils.mjs",
+			"types": "./dist/lib/utils.d.mts"
+		},
+		"./lib/zod": {
+			"default": "./dist/lib/zod/index.mjs",
+			"types": "./dist/lib/zod/index.d.mts"
+		},
+		"./lib/zod/codecs": {
+			"default": "./dist/lib/zod/codecs/index.mjs",
+			"types": "./dist/lib/zod/codecs/index.d.mts"
+		},
+		"./lib/zod/codecs/json": {
+			"default": "./dist/lib/zod/codecs/json.mjs",
+			"types": "./dist/lib/zod/codecs/json.d.mts"
+		},
+		"./lib/zod/utils": {
+			"default": "./dist/lib/zod/utils.mjs",
+			"types": "./dist/lib/zod/utils.d.mts"
+		},
+		"./types": {
+			"default": "./dist/types/index.mjs",
+			"types": "./dist/types/index.d.mts"
+		},
+		"./types/utils": {
+			"default": "./dist/types/utils.mjs",
+			"types": "./dist/types/utils.d.mts"
+		},
+		"./types/zod": {
+			"default": "./dist/types/zod.mjs",
+			"types": "./dist/types/zod.d.mts"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist"
+	],
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"repository": {
+		"url": "git+https://github.com/padosoft/ts-support.git"
+	},
+	"scripts": {
+		"build": "tsdown",
+		"ts:check": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@padosoft/config": "workspace:^"
+	},
+	"dependencies": {},
+	"peerDependencies": {
+		"zod": "^4.0.0"
+	}
+}