@medyll/idae-idbql 0.177.0 → 0.178.0

package/dist/idbqlCore/types.d.ts

@@ -1,12 +1,20 @@
+/**
+ * Utility type to expand a type's properties for better type inference and hover display.
+ * @template T - The type to expand.
+ */
 export type ExpandProps<T> = T extends infer O ? {
     [K in keyof O]: O[K];
 } : never;
+/**
+ * Enumeration of primitive field types supported by the schema system.
+ * Used for type-safe field declarations in collection templates.
+ */
 export declare enum enumPrimitive {
     id = "id",
     any = "any",
     date = "date",
     text = "text",
-    number = "number",// IdbqModelCollectionTemplate
+    number = "number",
     boolean = "boolean",
     datetime = "datetime",
     url = "url",
@@ -15,24 +23,84 @@ export declare enum enumPrimitive {
     time = "time",
     password = "password"
 }
+/**
+ * Enumeration of special field properties for schema fields.
+ * - private: Field is internal and not exposed externally.
+ * - readonly: Field cannot be modified after creation.
+ * - required: Field must be present in the data model.
+ */
 export declare enum TplProperties {
     private = "private",
     readonly = "readonly",
     required = "required"
 }
+/**
+ * Recursively generates all possible space-separated combinations of a set of string literals.
+ * Used to create all valid combinations of field properties (e.g., 'private readonly', etc).
+ * @template T - The set of string literals to combine.
+ * @template U - The set of remaining string literals (for recursion).
+ */
 export type CombineElements<T extends string, U extends string = T> = T | (T extends any ? `${T} ${CombineElements<Exclude<U, T>>}` : never);
-export type CombinedArgs = CombineElements<TplProperties>;
+/**
+ * Utility type to force TypeScript to expand a union or intersection for better hover display.
+ * @template T - The type to expand.
+ */
+type Expand<T> = T extends infer O ? {
+    [K in keyof O]: O[K];
+} : never;
+/**
+ * All valid combinations of TplProperties, including single and multi-property combinations.
+ * Used for field argument validation and schema typing.
+ */
+export type CombinedArgs = Expand<keyof typeof TplProperties | CombineElements<keyof typeof TplProperties>>;
+/**
+ * Utility type to represent array or object wrappers for a given primitive type string.
+ * E.g., 'array-of-text', 'object-number'.
+ * @template T - The base type string.
+ */
 export type IdbObjectify<T extends string> = `array-of-${T}` | `object-${T}`;
+/**
+ * Represents the fields of a collection template as a mapping from field name to type string.
+ */
 export type TplCollectionFields = Record<string, string>;
+/**
+ * Represents all valid primitive field type strings for a collection field.
+ * Includes enumPrimitive keys, text variants, dot-paths, and foreign key references.
+ * @template T - (Unused, for future extension)
+ */
 export type TplFieldPrimitive<T = {}> = keyof typeof enumPrimitive | `text-${'tiny' | 'short' | 'medium' | 'long' | 'area'}` | `${string}.${string}` | `fk-${string}.${string}`;
+/**
+ * Represents object or array wrappers for primitive field types.
+ */
 export type TplObjectFieldPrimitive = IdbObjectify<TplFieldPrimitive>;
+/**
+ * Represents a foreign key field type string (e.g., 'fk-users.id').
+ */
 export type TplFieldFk = `fk-${string}.${string}`;
+/**
+ * Represents object or array wrappers for foreign key field types.
+ */
 export type TplFkObject = IdbObjectify<TplFieldFk>;
+/**
+ * Union of all valid field type strings for a collection field, including primitives, objects, and foreign keys.
+ */
 export type TplTypes = TplFieldPrimitive | TplObjectFieldPrimitive | TplFieldFk | TplFkObject;
+/**
+ * Represents a field type string with property arguments, e.g., 'text (readonly required)'.
+ */
 export type TplFieldArgs = `${TplTypes} (${CombinedArgs})`;
-/** rules */
+/**
+ * Represents the allowed rules for a field: either a type string or a type string with arguments.
+ */
 export type TplFieldRules = TplFieldArgs | TplTypes;
+/**
+ * Alias for TplFieldRules, used for clarity in some contexts.
+ */
 export type TplFieldType = TplFieldArgs | TplTypes;
+/**
+ * Helper type for schema/field construction utilities.
+ * Used internally for dynamic schema building and validation.
+ */
 export type IDbForge = {
     collection?: TplCollectionName;
     fieldName?: keyof TplFields;
@@ -41,23 +109,65 @@ export type IDbForge = {
     fieldArgs?: [keyof typeof TplProperties] | undefined;
     is: any;
 };
+/**
+ * Main model type for describing the schema of an IndexedDB database.
+ * Maps collection names to their CollectionModel definitions.
+ * @template T - The shape of the collections in the database.
+ */
 export type IdbqModel<T = Record<string, Record<string, any>>> = {
     readonly [K in keyof T]: CollectionModel<T[K]>;
 };
+/**
+ * Type alias for a collection name in the schema model.
+ */
 export type TplCollectionName<T = TplCollectionFields> = keyof IdbqModel<T>;
+/**
+ * Type alias for the template property of a CollectionModel.
+ */
 export type Tpl<T = TplCollectionFields> = CollectionModel<T>['template'];
+/**
+ * Type alias for the fields property of a CollectionModel's template.
+ */
 export type TplFields<T = TplCollectionFields> = CollectionModel<T>['template']['fields'];
+/**
+ * Describes the structure and metadata for a single collection in the database schema.
+ * Includes keyPath, TypeScript type, and template (fields, indexes, FKs, etc).
+ * @template T - The shape of the collection's fields.
+ */
 export type CollectionModel<T = TplCollectionFields> = {
+    /**
+     * The key path (primary key) for the collection in IndexedDB.
+     */
     keyPath: string | any;
-    /** @deprecated use ts instead */
+    /**
+     * @deprecated Use 'ts' instead for type safety.
+     */
     model: any;
+    /**
+     * The TypeScript type representing the collection's data shape.
+     */
     ts: any;
+    /**
+     * Template metadata for the collection: fields, indexes, presentation, and foreign keys.
+     */
     template: {
+        /**
+         * The main index field for the collection.
+         */
         index: string;
+        /**
+         * Presentation string for UI or display purposes (combination of field names).
+         */
         presentation: CombineElements<Extract<keyof CollectionModel<T>['ts'], string>>;
+        /**
+         * Field definitions for the collection.
+         */
         fields: {
             [K in keyof T]: TplFieldRules;
         };
+        /**
+         * Foreign key definitions for the collection.
+         */
         fks: {
             [K in TplCollectionName]?: {
                 code: K;
@@ -67,3 +177,4 @@ export type CollectionModel<T = TplCollectionFields> = {
         };
     };
 };
+export {};

package/dist/idbqlCore/types.js

@@ -1,3 +1,7 @@
+/**
+ * Enumeration of primitive field types supported by the schema system.
+ * Used for type-safe field declarations in collection templates.
+ */
 export var enumPrimitive;
 (function (enumPrimitive) {
     enumPrimitive["id"] = "id";
@@ -13,6 +17,12 @@ export var enumPrimitive;
     enumPrimitive["time"] = "time";
     enumPrimitive["password"] = "password";
 })(enumPrimitive || (enumPrimitive = {}));
+/**
+ * Enumeration of special field properties for schema fields.
+ * - private: Field is internal and not exposed externally.
+ * - readonly: Field cannot be modified after creation.
+ * - required: Field must be present in the data model.
+ */
 export var TplProperties;
 (function (TplProperties) {
     TplProperties["private"] = "private";

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export * from './state/idbstate.svelte.js';
 export * from './state/idbqlEvent.svelte.js';
 export * from './scripts/types.js';
-export * from './path/pathResolver.js';
 export * from './idbqlCore/types.js';
 export * from './idbqlCore/idbqlSchema.js';
 export * from './idbqlCore/idbqlCore.js';
+export * from './path/pathResolver.js';
 export * from './collection/collection.svelte.js';

package/dist/index.js

@@ -2,8 +2,8 @@
 export * from './state/idbstate.svelte.js';
 export * from './state/idbqlEvent.svelte.js';
 export * from './scripts/types.js';
-export * from './path/pathResolver.js';
 export * from './idbqlCore/types.js';
 export * from './idbqlCore/idbqlSchema.js';
 export * from './idbqlCore/idbqlCore.js';
+export * from './path/pathResolver.js';
 export * from './collection/collection.svelte.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@medyll/idae-idbql",
   "scope": "@medyll",
-  "version": "0.177.0",
+  "version": "0.178.0",
   "description": "A powerful and flexible IndexedDB query library for TypeScript and JavaScript applications, offering a MongoDB-like query interface, strong TypeScript support, reactive state management, and easy integration with front-end frameworks like Svelte.",
   "exports": {
     ".": {
@@ -31,7 +31,7 @@
     "typescript": "^5.8.3",
     "vite": "^6.3.2",
     "@medyll/idae-prettier-config": "1.2.1",
-    "@medyll/idae-query": "0.178.0"
+    "@medyll/idae-query": "0.179.0"
   },
   "svelte": "./dist/index.js",
   "types": "./dist/index.d.ts",