@marianmeres/collection-types 1.0.1

package/AGENTS.md

@@ -0,0 +1,46 @@
+# CLAUDE.md
+
+## Project Overview
+
+Type-only package for the @marianmeres ecosystem. No runtime code - pure TypeScript type definitions.
+
+## Structure
+
+```
+src/
+├── mod.ts          # Main entry point, re-exports all modules
+├── utils.ts        # Branded types (UUID, ISODateString, LtreePath) and helpers
+├── model.ts        # Model entity types (DTOIn → DTOOut → DbRow pattern)
+├── collection.ts   # Collection entity types
+├── relation.ts     # Relation and RelationType entity types
+├── schema.ts       # JSON Schema extensions for UI/form generation
+├── api.ts          # API response wrappers, pagination, query syntax
+├── asset.ts        # File attachment types
+└── adapter.ts      # Database adapter interface types
+```
+
+## Key Patterns
+
+- **DTO Layering**: `DTOIn` (input) → `DTOOut` (+ server fields) → `DbRow` (+ internal fields)
+- **Branded Types**: `UUID`, `ISODateString`, `LtreePath` for compile-time safety
+- **Internal Fields**: Prefixed with `__` (e.g., `__is_rest_disabled`, `__searchable`)
+- **Server Fields**: Prefixed with `_` (e.g., `_created_at`, `_updated_at`)
+
+## Build & Publish
+
+```bash
+deno task rp        # Release patch + publish to JSR and npm
+deno task rpm       # Release minor + publish
+deno check src/mod.ts  # Type check
+```
+
+## Related Packages
+
+- `@marianmeres/condition-builder` - QueryOperator type is mirrored from here
+- Uses Deno for development, publishes to both JSR and npm
+
+## Notes
+
+- All exports have JSDoc comments
+- Flat file structure (no subdirectories in src/)
+- Formatting: tabs, 4-space indent width, 90 char line width

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marian Meres
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @marianmeres/collection-types
+
+Shared type definitions for internal use within the @marianmeres ecosystem. Type-only package with no runtime code.

package/dist/adapter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Adapter types for the collection system.
+ * Defines database query provider and adapter configuration.
+ */
+/**
+ * Generic database query result.
+ * Modeled after pg.QueryResult but adapter-agnostic.
+ */
+export interface DbQueryResult<T = Record<string, unknown>> {
+    /** Result rows */
+    rows: T[];
+    /** Number of rows affected (for INSERT/UPDATE/DELETE) */
+    rowCount?: number;
+}
+/**
+ * Database query provider interface.
+ * Abstracts the underlying database implementation.
+ */
+export interface QueryProvider {
+    /** Query provider type */
+    type: "pg" | "sqlite";
+    /** Execute a query and return results */
+    query(sql: string, params?: unknown[]): Promise<DbQueryResult>;
+    /** Execute a query with cursor-style row iteration */
+    each(sql: string, params: unknown[], onRow: (row: Record<string, unknown>) => Promise<void>): Promise<void>;
+}
+/**
+ * Adapter configuration options.
+ */
+export interface AdapterOptions {
+    /** Prefix for table names */
+    tablePrefix: string;
+    /** SQL to execute before initialization */
+    preInitSql: string;
+    /** SQL to execute after initialization */
+    postInitSql: string;
+    /** Custom SQL for userland initialization */
+    customPreInitSql: string;
+    /** Foreign key constraint to project table */
+    projectIdFk: null | {
+        table: string;
+        column: string;
+    };
+    /** Reset all data before initialization (tests only) */
+    resetAll: boolean;
+}

package/dist/adapter.js

@@ -0,0 +1,5 @@
+/**
+ * Adapter types for the collection system.
+ * Defines database query provider and adapter configuration.
+ */
+export {};

package/dist/api.d.ts

@@ -0,0 +1,76 @@
+/**
+ * API types for the collection system.
+ * Defines response structures and query syntax.
+ */
+import type { Collection } from "./collection.js";
+import type { Model } from "./model.js";
+import type { RelationType } from "./relation.js";
+/**
+ * Pagination metadata for list responses.
+ */
+export interface PaginationMeta {
+    /** Number of items per page */
+    limit: number;
+    /** Number of items skipped */
+    offset: number;
+    /** Total number of items available */
+    total?: number;
+    /** Whether more items exist beyond this page */
+    hasMore?: boolean;
+}
+/**
+ * Standard API response wrapper.
+ */
+export interface ApiResponse<T = unknown> {
+    /** Response payload */
+    data: T;
+    /** Response metadata */
+    meta?: Record<string, unknown>;
+}
+/**
+ * API response for list endpoints with pagination.
+ */
+export interface ApiListResponse<T = unknown> extends ApiResponse<T[]> {
+    /** Pagination and additional metadata */
+    meta: PaginationMeta & Record<string, unknown>;
+    /** Related data included in response */
+    included?: {
+        collection?: Record<string, Collection>;
+        relation_type?: Record<string, RelationType>;
+        model?: Record<string, Model>;
+    };
+}
+/**
+ * Query operators for filtering.
+ * Mirrored from @marianmeres/condition-builder OPERATOR.
+ */
+export type QueryOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like" | "nlike" | "match" | "nmatch" | "is" | "nis" | "in" | "nin" | "ltree" | "ancestor" | "descendant";
+/**
+ * Single query condition.
+ */
+export interface QueryCondition {
+    /** Field name to filter on */
+    field: string;
+    /** Comparison operator */
+    operator: QueryOperator;
+    /** Value to compare against */
+    value: unknown;
+}
+/**
+ * Query syntax for list endpoints.
+ * Defines filtering, sorting, and pagination.
+ */
+export interface QuerySyntax {
+    /** Filter conditions */
+    where?: QueryCondition | QueryCondition[];
+    /** Full-text search query */
+    search?: string;
+    /** Field to sort by */
+    order?: string;
+    /** Sort ascending (true) or descending (false) */
+    asc?: boolean;
+    /** Number of items to return */
+    limit?: number;
+    /** Number of items to skip */
+    offset?: number;
+}

package/dist/api.js

@@ -0,0 +1,5 @@
+/**
+ * API types for the collection system.
+ * Defines response structures and query syntax.
+ */
+export {};

package/dist/asset.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Asset types for the collection system.
+ * Assets are file attachments associated with models.
+ */
+import type { UUID, ISODateString } from "./utils.js";
+/**
+ * Variant of an asset (e.g., thumbnail, preview).
+ */
+export interface AssetVariant {
+    /** Variant name (e.g., "thumbnail", "large") */
+    name: string;
+    /** Width in pixels */
+    width?: number;
+    /** Height in pixels */
+    height?: number;
+    /** File format (e.g., "webp", "jpg") */
+    format?: string;
+    /** URL to access this variant */
+    url: string;
+}
+/**
+ * Asset data including file metadata and variants.
+ */
+export interface AssetData {
+    /** Original filename */
+    filename: string;
+    /** MIME type */
+    mimetype: string;
+    /** File size in bytes */
+    size: number;
+    /** URL to access the original file */
+    url: string;
+    /** Generated variants (thumbnails, previews, etc.) */
+    variants?: AssetVariant[];
+    /** Additional file metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Asset attached to a model.
+ */
+export interface ModelAsset {
+    /** Unique asset identifier */
+    asset_id: UUID;
+    /** Model this asset belongs to */
+    model_id: UUID;
+    /** Field name in the model schema */
+    field_name: string;
+    /** Sort order for multiple assets */
+    sort_order: number;
+    /** Asset file data */
+    data: AssetData;
+    /** Creation timestamp */
+    _created_at: ISODateString;
+    /** Last update timestamp */
+    _updated_at: ISODateString;
+}

package/dist/asset.js

@@ -0,0 +1,5 @@
+/**
+ * Asset types for the collection system.
+ * Assets are file attachments associated with models.
+ */
+export {};

package/dist/collection.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Collection types for the collection system.
+ * Collections are containers for models with schema definitions.
+ */
+import type { UUID, ISODateString, LtreePath, UserData } from "./utils.js";
+import type { PropertyDefinition } from "./schema.js";
+/**
+ * Definition for a folder within a collection.
+ * Folders organize models hierarchically.
+ */
+export interface FolderDefinition {
+    label?: string;
+    description?: string;
+    color?: string;
+}
+/**
+ * Definition for a tag within a collection.
+ * Tags provide cross-cutting categorization.
+ */
+export interface TagDefinition {
+    label?: string;
+    color?: string;
+}
+/**
+ * Input DTO for creating/updating a collection.
+ */
+export interface CollectionDTOIn {
+    /** Unique path identifier (ltree format) */
+    path: LtreePath;
+    /** Maximum number of models allowed (-1 for unlimited) */
+    cardinality?: number;
+    /** Model types allowed in this collection */
+    types?: string[];
+    /** JSON Schema definitions per model type */
+    schemas?: Record<string, Record<string, PropertyDefinition>>;
+    /** Default values per model type */
+    defaults?: Record<string, UserData>;
+    /** User-defined data */
+    data?: UserData;
+    /** User-defined metadata */
+    meta?: UserData;
+    /** Whether collection is hidden from listings */
+    is_unlisted?: boolean;
+    /** Whether collection can be deleted */
+    is_deletable?: boolean;
+    /** Whether collection is read-only */
+    is_readonly?: boolean;
+    /** Folder definitions */
+    folders?: Record<string, FolderDefinition>;
+    /** Tag definitions */
+    tags?: Record<string, TagDefinition>;
+}
+/**
+ * Output DTO for collection responses.
+ * Extends input fields with server-generated identifiers.
+ */
+export interface CollectionDTOOut extends CollectionDTOIn {
+    /** Unique collection identifier */
+    collection_id: UUID;
+    /** Project this collection belongs to */
+    project_id: UUID;
+    /** Creation timestamp */
+    _created_at: ISODateString;
+    /** Last update timestamp */
+    _updated_at: ISODateString;
+}
+/**
+ * Full database row representation of a collection.
+ */
+export interface CollectionDbRow extends CollectionDTOOut {
+    /** @internal Disables REST API access for entire collection */
+    __is_rest_disabled?: boolean;
+}
+/**
+ * Primary Collection type alias.
+ */
+export type Collection = CollectionDbRow;

package/dist/collection.js

@@ -0,0 +1,5 @@
+/**
+ * Collection types for the collection system.
+ * Collections are containers for models with schema definitions.
+ */
+export {};

package/dist/mod.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @module @marianmeres/collection-types
+ *
+ * Type definitions for the collection management system.
+ * Pure interfaces with no runtime code - safe for type-only imports.
+ *
+ * @example
+ * ```typescript
+ * import type {
+ *   Model,
+ *   Collection,
+ *   Relation,
+ *   RelationType,
+ *   PropertyDefinition,
+ *   ApiResponse,
+ *   UUID,
+ * } from "@marianmeres/collection-types";
+ * ```
+ */
+export * from "./utils.js";
+export * from "./model.js";
+export * from "./collection.js";
+export * from "./relation.js";
+export * from "./schema.js";
+export * from "./api.js";
+export * from "./asset.js";
+export * from "./adapter.js";

package/dist/mod.js

@@ -0,0 +1,33 @@
+/**
+ * @module @marianmeres/collection-types
+ *
+ * Type definitions for the collection management system.
+ * Pure interfaces with no runtime code - safe for type-only imports.
+ *
+ * @example
+ * ```typescript
+ * import type {
+ *   Model,
+ *   Collection,
+ *   Relation,
+ *   RelationType,
+ *   PropertyDefinition,
+ *   ApiResponse,
+ *   UUID,
+ * } from "@marianmeres/collection-types";
+ * ```
+ */
+// Utils (branded types, helpers)
+export * from "./utils.js";
+// Core entities
+export * from "./model.js";
+export * from "./collection.js";
+export * from "./relation.js";
+// Schema system
+export * from "./schema.js";
+// API layer
+export * from "./api.js";
+// Assets
+export * from "./asset.js";
+// Adapter (database layer)
+export * from "./adapter.js";

package/dist/model.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Model types for the collection system.
+ * Defines the structure of model records at different layers (input, output, database).
+ */
+import type { UUID, ISODateString, LtreePath, UserData, MaybeLocalized } from "./utils.js";
+/**
+ * Input DTO for creating/updating a model.
+ * Contains user-provided fields for model creation.
+ */
+export interface ModelDTOIn {
+    /** Model type within collection */
+    type?: string;
+    /** Parent model ID for hierarchy */
+    parent_id?: UUID | null;
+    /** Unique path identifier (ltree format) */
+    path?: LtreePath | null;
+    /** Folder for organization */
+    folder?: string | null;
+    /** Tags for categorization */
+    tags?: string[];
+    /** User-defined data */
+    data?: UserData;
+    /** User-defined metadata */
+    meta?: UserData;
+    /** Whether model is hidden from listings */
+    is_unlisted?: boolean;
+    /** Whether model can be deleted */
+    is_deletable?: boolean;
+    /** Whether model is read-only */
+    is_readonly?: boolean;
+    /** Whether model is starred/favorited */
+    is_starred?: boolean;
+    /** Whether model is enabled/active */
+    is_enabled?: boolean;
+    /** Color flags */
+    red?: boolean;
+    orange?: boolean;
+    yellow?: boolean;
+    green?: boolean;
+    blue?: boolean;
+    purple?: boolean;
+    gray?: boolean;
+}
+/**
+ * Output DTO for model responses.
+ * Extends input fields with server-generated identifiers and timestamps.
+ */
+export interface ModelDTOOut extends ModelDTOIn {
+    /** Unique model identifier */
+    model_id: UUID;
+    /** Collection this model belongs to */
+    collection_id: UUID;
+    /** Auto-generated label from schema _label_source fields */
+    _label?: MaybeLocalized<string> | null;
+    /** Computed label for hierarchy display */
+    _hierarchy_label?: string | null;
+    /** Creation timestamp */
+    _created_at: ISODateString;
+    /** Last update timestamp */
+    _updated_at: ISODateString;
+}
+/**
+ * Full database row representation of a model.
+ * Includes internal fields for search indexing and REST control.
+ */
+export interface ModelDbRow extends ModelDTOOut {
+    /** @internal Disables REST API access */
+    __is_rest_disabled?: boolean;
+    /** @internal Structured search index data */
+    __searchable?: Record<string, unknown>;
+    /** @internal Full-text search string */
+    __searchable2?: string;
+    /** @internal Cached hierarchy path for ancestor queries */
+    __hierarchy_path?: LtreePath | null;
+}
+/**
+ * Model data with relation definitions for upsert operations.
+ * The __relations__ field is processed separately during save.
+ */
+export interface ModelUpsertData extends ModelDbRow {
+    /** Relations to save with model (relation_type -> array of related model IDs) */
+    __relations__?: Record<string, UUID[]>;
+}
+/**
+ * Primary Model type with generic data typing.
+ * Use Model<MyDataType> for type-safe data access.
+ *
+ * @example
+ * ```typescript
+ * interface BookData {
+ *   title: string;
+ *   author: string;
+ *   isbn: string;
+ * }
+ * type Book = Model<BookData>;
+ * ```
+ */
+export type Model<TData extends UserData = UserData> = ModelDbRow & {
+    data: TData;
+};

package/dist/model.js

@@ -0,0 +1,5 @@
+/**
+ * Model types for the collection system.
+ * Defines the structure of model records at different layers (input, output, database).
+ */
+export {};

package/dist/relation.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Relation types for the collection system.
+ * Relations link models across collections with typed relationships.
+ */
+import type { UUID, ISODateString, UserData } from "./utils.js";
+/**
+ * Input DTO for creating/updating a relation type.
+ * A RelationType defines a typed relationship between models from different collections.
+ *
+ * @example
+ * ```typescript
+ * const input: RelationTypeDTOIn = {
+ *   relation_type: "author",
+ *   model_collection_id: "books",
+ *   related_collection_id: "people",
+ * };
+ * ```
+ */
+export interface RelationTypeDTOIn {
+    /** Project identifier */
+    project_id?: UUID;
+    /** Unique relation type name (business key) */
+    relation_type?: string;
+    /** Collection ID of the "from" models */
+    model_collection_id?: UUID;
+    /** Collection ID of the "to" models (for strong relations) */
+    related_collection_id?: UUID;
+    /** Optional type filter for related models */
+    related_collection_model_type?: string;
+    /** Maximum number of relations allowed (-1 for unlimited) */
+    cardinality?: number;
+    /** Cardinality on the model side (1 = one-to-many, -1 = many-to-many) */
+    model_cardinality?: number;
+    /** Cardinality on the related side */
+    related_cardinality?: number;
+    /** Whether relation type is hidden from listings */
+    is_unlisted?: boolean;
+    /** Whether relation type can be deleted */
+    is_deletable?: boolean;
+    /** Whether relation type is read-only */
+    is_readonly?: boolean;
+    /** Additional metadata */
+    meta?: UserData;
+}
+/**
+ * Output DTO for relation type responses.
+ */
+export interface RelationTypeDTOOut extends RelationTypeDTOIn {
+    /** Unique relation type identifier */
+    _relation_type_id: UUID;
+    /** Creation timestamp */
+    _created_at: ISODateString;
+    /** Last update timestamp */
+    _updated_at: ISODateString;
+}
+/**
+ * Full database row representation of a relation type.
+ */
+export interface RelationTypeDbRow extends RelationTypeDTOOut {
+    /** @internal Disables REST API access */
+    __is_rest_disabled?: boolean;
+}
+/**
+ * Primary RelationType type alias.
+ */
+export type RelationType = RelationTypeDbRow;
+/**
+ * Input DTO for creating/updating a relation instance.
+ * A Relation is a link between two models through a RelationType.
+ *
+ * @example
+ * ```typescript
+ * const input: RelationDTOIn = {
+ *   related_id: "uuid-of-related-model",
+ *   sort_order: 1,
+ * };
+ * ```
+ */
+export interface RelationDTOIn {
+    /** UUID of the strongly-related model (must exist in related collection) */
+    related_id?: UUID;
+    /** Arbitrary string for weak references (when related item doesn't exist as model) */
+    weak_related_id?: string;
+    /** Sort order for displaying relations */
+    sort_order?: number;
+    /** Whether relation is hidden from listings */
+    is_unlisted?: boolean;
+    /** Whether relation can be deleted */
+    is_deletable?: boolean;
+    /** Whether relation is read-only */
+    is_readonly?: boolean;
+    /** Additional metadata */
+    meta?: UserData;
+}
+/**
+ * Output DTO for relation responses.
+ */
+export interface RelationDTOOut extends RelationDTOIn {
+    /** Unique relation identifier */
+    relation_id: UUID;
+    /** Relation type identifier */
+    _relation_type_id: UUID;
+    /** Source model identifier */
+    model_id: UUID;
+    /** Creation timestamp */
+    _created_at: ISODateString;
+    /** Last update timestamp */
+    _updated_at: ISODateString;
+}
+/**
+ * Full database row representation of a relation.
+ */
+export interface RelationDbRow extends RelationDTOOut {
+}
+/**
+ * Primary Relation type alias.
+ */
+export type Relation = RelationDbRow;

package/dist/relation.js

@@ -0,0 +1,5 @@
+/**
+ * Relation types for the collection system.
+ * Relations link models across collections with typed relationships.
+ */
+export {};

package/dist/schema.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Schema types for the collection system.
+ * Defines JSON Schema extensions and UI configuration.
+ */
+/** HTML field type for UI rendering */
+export type SchemaHtmlType = "text" | "textarea" | "wysiwyg" | "number" | "boolean" | "select" | "multiselect" | "date" | "datetime" | "time" | "color" | "relation" | "asset" | "json" | "code";
+/** Configuration for relation-type fields in schema */
+export interface RelationTypeConfig {
+    relation_type: string;
+    domain?: string;
+    entity?: string;
+    cardinality?: number;
+}
+/** Configuration for asset-type fields in schema */
+export interface AssetTypeConfig {
+    accept?: string[];
+    maxSize?: number;
+    variants?: string[];
+}
+/** Configuration for select/multiselect fields */
+export interface SelectConfig {
+    options: Array<{
+        value: string;
+        label: string;
+    }>;
+    multiple?: boolean;
+}
+/** Configuration for _html schema keyword */
+export interface SchemaHtmlConfig {
+    type: SchemaHtmlType;
+    _type_config?: RelationTypeConfig | AssetTypeConfig | SelectConfig;
+    rows?: number;
+    placeholder?: string;
+    help?: string;
+    readonly?: boolean;
+    hidden?: boolean;
+}
+/**
+ * Custom JSON Schema keywords for collection system.
+ * These extend standard JSON Schema with collection-specific metadata.
+ */
+export interface CustomSchemaKeywords {
+    /** Default value for property */
+    _default?: unknown;
+    /** UI hint configuration object */
+    _html?: SchemaHtmlConfig;
+    /** Property title for display */
+    _title?: string;
+    /** Property description for display */
+    _description?: string;
+    /** Property used as model label (number, priority 1=highest) */
+    _label_source?: number;
+    /** Allow building hierarchy from label slashes */
+    _label_source_allow_build_hierarchy?: boolean;
+    /** Path uniqueness constraint */
+    _unique?: boolean;
+    /** Include in full-text search */
+    _searchable?: boolean;
+    /** Array of filters to apply before indexing */
+    _searchable_filters?: string[];
+    /** Type ordering */
+    _order?: number;
+}
+/**
+ * Property definition extending JSON Schema with custom keywords.
+ * Used in collection schemas to define model fields.
+ */
+export interface PropertyDefinition extends CustomSchemaKeywords {
+    type?: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+    format?: string;
+    enum?: unknown[];
+    items?: PropertyDefinition;
+    properties?: Record<string, PropertyDefinition>;
+    required?: string[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    default?: unknown;
+}
+/**
+ * Model type definition within a collection.
+ * Defines the schema for a specific model type.
+ */
+export interface ModelDefinition {
+    properties: Record<string, PropertyDefinition>;
+    required?: string[];
+}

package/dist/schema.js

@@ -0,0 +1,5 @@
+/**
+ * Schema types for the collection system.
+ * Defines JSON Schema extensions and UI configuration.
+ */
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Utility types for the collection system.
+ * Includes branded types for compile-time safety and common helper types.
+ */
+/** Branded type for UUID strings */
+export type UUID = string & {
+    readonly __brand: "UUID";
+};
+/** Branded type for ISO 8601 date strings */
+export type ISODateString = string & {
+    readonly __brand: "ISODateString";
+};
+/** Branded type for PostgreSQL ltree paths */
+export type LtreePath = string & {
+    readonly __brand: "LtreePath";
+};
+/** Value that may be localized with language keys */
+export type MaybeLocalized<T> = T | Record<string, T>;
+/** JSON-compatible primitive */
+export type JsonPrimitive = string | number | boolean | null;
+/** JSON-compatible object */
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/** JSON-compatible array */
+export type JsonArray = JsonValue[];
+/** JSON-compatible value (recursive) */
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+/** User-provided flexible data */
+export type UserData = Record<string, unknown>;
+/** Helper to create a branded type */
+export type Brand<T, B extends string> = T & {
+    readonly __brand: B;
+};

package/dist/utils.js

@@ -0,0 +1,5 @@
+/**
+ * Utility types for the collection system.
+ * Includes branded types for compile-time safety and common helper types.
+ */
+export {};

package/package.json

@@ -0,0 +1,23 @@
+{
+	"name": "@marianmeres/collection-types",
+	"version": "1.0.1",
+	"type": "module",
+	"main": "dist/mod.js",
+	"types": "dist/mod.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"import": "./dist/mod.js"
+		}
+	},
+	"author": "Marian Meres",
+	"license": "MIT",
+	"dependencies": {},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/marianmeres/collection-types.git"
+	},
+	"bugs": {
+		"url": "https://github.com/marianmeres/collection-types/issues"
+	}
+}