@lix-js/sdk 0.5.0 → 0.6.0-preview.0

package/src/engine/entity-views/entity-state-by-version.ts

@@ -1,263 +0,0 @@
-import type { Generated } from "kysely";
-import type { LixGenerated } from "../../schema-definition/definition.js";
-
-/**
- * Base type for cross-version entity views that include operational columns from the state table.
- * These views expose lixcol_version_id for version-specific operations and allow querying entities
- * across all versions in the database.
- *
- * @example
- * ```typescript
- * // Define an entity view type for cross-version operations
- * export type AccountByVersionView = {
- *   id: Generated<string>;
- *   name: string;
- * } & StateEntityByVersionView;
- *
- * // Query entities across versions
- * const accounts = await lix.db
- *   .selectFrom("account_by_version")
- *   .where("lixcol_version_id", "=", "v1")
- *   .selectAll()
- *   .execute();
- * ```
- */
-export type StateEntityByVersionView = {
-	/**
-	 * The unique identifier for this entity within its schema and file.
-	 *
-	 * This is the primary identifier used to reference this specific entity.
-	 */
-	lixcol_entity_id: Generated<string>;
-
-	/**
-	 * The schema key that defines the structure and type of this entity.
-	 *
-	 * This references the schema definition that validates and types this entity.
-	 */
-	lixcol_schema_key: Generated<string>;
-
-	/**
-	 * File identifier where this entity is stored.
-	 *
-	 * This references the file_id in the state table and links the entity
-	 * to a specific file in the Lix file system.
-	 */
-	lixcol_file_id: Generated<string>;
-
-	/**
-	 * The plugin key that manages this entity type.
-	 *
-	 * This identifies which plugin is responsible for handling this entity.
-	 */
-	lixcol_plugin_key: Generated<string>;
-
-	/**
-	 * Version identifier for this specific state of the entity.
-	 *
-	 * This column allows you to query and modify entities in specific versions.
-	 * Each version may have its own state for the same entity.
-	 */
-	lixcol_version_id: Generated<string>;
-
-	/**
-	 * Version identifier this entity was inherited from during branching.
-	 *
-	 * - `null` if the entity was created in this version
-	 * - Contains the source version_id if the entity was inherited from another version
-	 *
-	 * This is useful for tracking entity lineage across version branches.
-	 */
-	lixcol_inherited_from_version_id: Generated<string | null>;
-
-	/**
-	 * Timestamp when this entity was created in this version.
-	 *
-	 * **Important**: This timestamp is relative to the version specified by lixcol_version_id.
-	 * - When an entity is first created, this is the actual creation time
-	 * - When an entity is inherited from another version, this is the time it was inherited
-	 *
-	 * Format: ISO 8601 string (e.g., "2024-03-20T10:30:00.000Z")
-	 */
-	lixcol_created_at: Generated<string>;
-
-	/**
-	 * Timestamp when this entity was last updated in this version.
-	 *
-	 * **Important**: This timestamp is relative to the version specified by lixcol_version_id.
-	 * - Updates only when the entity is modified within this specific version
-	 * - When first inherited, this equals lixcol_created_at
-	 *
-	 * Format: ISO 8601 string (e.g., "2024-03-20T10:30:00.000Z")
-	 */
-	lixcol_updated_at: Generated<string>;
-
-	/**
-	 * Change identifier for the last modification to this entity.
-	 *
-	 * This references the change.id that last modified this entity, enabling
-	 * blame and diff functionality. Useful for tracking who made changes
-	 * and when they were made.
-	 */
-	lixcol_change_id: Generated<string>;
-
-	/**
-	 * Whether this entity is stored as untracked state.
-	 *
-	 * - `false` (default): Entity follows normal change control and versioning
-	 * - `true`: Entity bypasses change control for UI state, temporary data, etc.
-	 *
-	 * Untracked entities don't create change records and have highest priority
-	 * in the state resolution order: untracked > tracked > inherited.
-	 */
-	lixcol_untracked: Generated<boolean>;
-
-	/**
-	 * Commit identifier that contains this entity's last change.
-	 *
-	 * This references the commit.id that contains the last change to this entity.
-	 * Useful for understanding which commit a particular entity state belongs to,
-	 * enabling history queries and version comparison.
-	 */
-	lixcol_commit_id: Generated<string>;
-
-	/**
-	 * Writer key associated with the last mutation that produced this entity state.
-	 *
-	 * Used to attribute writes to individual clients/sessions for echo suppression.
-	 * Null when no writer key was set for the mutation.
-	 */
-	lixcol_writer_key: Generated<string | null>;
-
-	/**
-	 * Arbitrary metadata attached to the change that produced this entity state.
-	 */
-	lixcol_metadata: Generated<Record<string, any> | null>;
-};
-
-/**
- * Base type for cross-version cross-version entity views using LixGenerated markers instead of Kysely's Generated type.
- * This type is compatible with the Lix SDK's type transformation system and allows
- * cross-version entity operations.
- *
- * @example
- * ```typescript
- * // Define an entity type for cross-version operations
- * export type Account = {
- *   id: LixGenerated<string>;
- *   name: string;
- * } & EntityStateByVersionColumns;
- * ```
- */
-export type EntityStateByVersionColumns = {
-	/**
-	 * The unique identifier for this entity within its schema and file.
-	 *
-	 * This is the primary identifier used to reference this specific entity.
-	 */
-	lixcol_entity_id: LixGenerated<string>;
-
-	/**
-	 * The schema key that defines the structure and type of this entity.
-	 *
-	 * This references the schema definition that validates and types this entity.
-	 */
-	lixcol_schema_key: LixGenerated<string>;
-
-	/**
-	 * File identifier where this entity is stored.
-	 *
-	 * This references the file_id in the state table and links the entity
-	 * to a specific file in the Lix file system.
-	 */
-	lixcol_file_id: LixGenerated<string>;
-
-	/**
-	 * The plugin key that manages this entity type.
-	 *
-	 * This identifies which plugin is responsible for handling this entity.
-	 */
-	lixcol_plugin_key: LixGenerated<string>;
-
-	/**
-	 * Version identifier for this specific state of the entity.
-	 *
-	 * This column allows you to query and modify entities in specific versions.
-	 * Each version may have its own state for the same entity.
-	 */
-	lixcol_version_id: LixGenerated<string>;
-
-	/**
-	 * Timestamp when this entity was created in this version.
-	 *
-	 * **Important**: This timestamp is relative to the version specified by lixcol_version_id.
-	 * - When an entity is first created, this is the actual creation time
-	 * - When an entity is inherited from another version, this is the time it was inherited
-	 *
-	 * Format: ISO 8601 string (e.g., "2024-03-20T10:30:00.000Z")
-	 */
-	lixcol_created_at: LixGenerated<string>;
-
-	/**
-	 * Timestamp when this entity was last updated in this version.
-	 *
-	 * **Important**: This timestamp is relative to the version specified by lixcol_version_id.
-	 * - Updates only when the entity is modified within this specific version
-	 * - When first inherited, this equals lixcol_created_at
-	 *
-	 * Format: ISO 8601 string (e.g., "2024-03-20T10:30:00.000Z")
-	 */
-	lixcol_updated_at: LixGenerated<string>;
-
-	/**
-	 * Version identifier this entity was inherited from during branching.
-	 *
-	 * - `null` if the entity was created in this version
-	 * - Contains the source version_id if the entity was inherited from another version
-	 *
-	 * This is useful for tracking entity lineage across version branches.
-	 */
-	lixcol_inherited_from_version_id: LixGenerated<string | null>;
-
-	/**
-	 * Change identifier for the last modification to this entity.
-	 *
-	 * This references the change.id that last modified this entity, enabling
-	 * blame and diff functionality. Useful for tracking who made changes
-	 * and when they were made.
-	 */
-	lixcol_change_id: LixGenerated<string>;
-
-	/**
-	 * Whether this entity is stored as untracked state.
-	 *
-	 * - `false` (default): Entity follows normal change control and versioning
-	 * - `true`: Entity bypasses change control for UI state, temporary data, etc.
-	 *
-	 * Untracked entities don't create change records and have highest priority
-	 * in the state resolution order: untracked > tracked > inherited.
-	 */
-	lixcol_untracked: LixGenerated<boolean>;
-
-	/**
-	 * Commit identifier that contains this entity's last change.
-	 *
-	 * This references the commit.id that contains the last change to this entity.
-	 * Useful for understanding which commit a particular entity state belongs to,
-	 * enabling history queries and version comparison.
-	 */
-	lixcol_commit_id: LixGenerated<string>;
-
-	/**
-	 * Writer key associated with the last mutation that produced this entity state.
-	 *
-	 * Used to attribute writes to individual clients/sessions for echo suppression.
-	 * Null when no writer key was set for the mutation.
-	 */
-	lixcol_writer_key: LixGenerated<string | null>;
-
-	/**
-	 * Arbitrary metadata attached to the change that produced this entity state.
-	 */
-	lixcol_metadata: LixGenerated<Record<string, any> | null>;
-};

package/src/engine/entity-views/entity-state-history.ts

@@ -1,208 +0,0 @@
-import type { Generated } from "kysely";
-import type { LixGenerated } from "../../schema-definition/definition.js";
-
-/**
- * Base type for entity history views that include historical data from the state_history table.
- * These views provide access to entity states at different points in change set history,
- * enabling features like blame functionality and historical diffs.
- *
- * History views are read-only and show how entities evolved over time through changes.
- *
- * @example
- * ```typescript
- * // Define an entity history view type
- * export type AccountHistoryView = {
- *   id: Generated<string>;
- *   name: string;
- * } & StateEntityHistoryView;
- *
- * // Query entity history at a specific commit
- * const history = await lix.db
- *   .selectFrom("account_history")
- *   .where("lixcol_commit_id", "=", commitId)
- *   .where("lixcol_depth", "=", 0) // Get the state at this exact commit
- *   .selectAll()
- *   .execute();
- * ```
- */
-export type StateEntityHistoryView = {
-	/**
-	 * The unique identifier for this entity within its schema and file.
-	 *
-	 * This is the primary identifier used to reference this specific entity.
-	 */
-	lixcol_entity_id: Generated<string>;
-
-	/**
-	 * The schema key that defines the structure and type of this entity.
-	 *
-	 * This references the schema definition that validates and types this entity.
-	 */
-	lixcol_schema_key: Generated<string>;
-
-	/**
-	 * File identifier where this entity is stored.
-	 *
-	 * This references the file_id in the state_history table and links the entity
-	 * to a specific file in the Lix file system.
-	 */
-	lixcol_file_id: Generated<string>;
-
-	/**
-	 * Plugin identifier that manages this entity type.
-	 *
-	 * This identifies which plugin is responsible for this entity's behavior
-	 * and schema definition.
-	 */
-	lixcol_plugin_key: Generated<string>;
-
-	/**
-	 * Version of the schema used for this entity at this point in history.
-	 *
-	 * Format: "major.minor" (e.g., "1.0", "2.1")
-	 * This allows tracking schema evolution over time.
-	 */
-	lixcol_schema_version: Generated<string>;
-
-	/**
-	 * ID of the change that created this specific entity state.
-	 *
-	 * Each modification to an entity creates a new change, and this ID
-	 * references that specific change in the change table.
-	 */
-	lixcol_change_id: Generated<string>;
-
-	/**
-	 * Commit ID that serves as the query root for depth calculation.
-	 *
-	 * When querying history, this represents the "perspective" from which
-	 * you're viewing the entity's history. The depth is calculated relative
-	 * to this commit.
-	 */
-	lixcol_commit_id: Generated<string>;
-
-	/**
-	 * The root commit ID used as the starting point for traversing history.
-	 *
-	 * When querying history from a specific commit, this field contains that
-	 * commit ID for all returned rows. Used with `depth` to understand how
-	 * far back in history each entity state is from this root.
-	 */
-	lixcol_root_commit_id: Generated<string>;
-
-	/**
-	 * Depth of this entity state relative to the queried commit_id.
-	 *
-	 * - `0`: The entity state at the exact queried commit
-	 * - `1`: The entity state one commit before the queried commit
-	 * - `2+`: Earlier states, going back in history
-	 *
-	 * This is useful for blame functionality and understanding how an entity
-	 * evolved to reach its current state.
-	 */
-	lixcol_depth: Generated<number>;
-
-	/**
-	 * Arbitrary metadata attached to the change that produced this historical state.
-	 */
-	lixcol_metadata: Generated<Record<string, any> | null>;
-};
-
-/**
- * Base type for entity history views using LixGenerated markers instead of Kysely's Generated type.
- * This type is compatible with the Lix SDK's type transformation system and provides
- * access to historical entity states.
- *
- * History views are read-only and show how entities evolved over time through changes.
- *
- * @example
- * ```typescript
- * // Define an entity history type
- * export type AccountHistory = {
- *   id: string;  // No LixGenerated marker in history views
- *   name: string;
- * } & StateEntityHistoryColumns;
- * ```
- */
-export type StateEntityHistoryColumns = {
-	/**
-	 * The unique identifier for this entity within its schema and file.
-	 *
-	 * This is the primary identifier used to reference this specific entity.
-	 */
-	lixcol_entity_id: LixGenerated<string>;
-
-	/**
-	 * The schema key that defines the structure and type of this entity.
-	 *
-	 * This references the schema definition that validates and types this entity.
-	 */
-	lixcol_schema_key: LixGenerated<string>;
-
-	/**
-	 * File identifier where this entity is stored.
-	 *
-	 * This references the file_id in the state_history table and links the entity
-	 * to a specific file in the Lix file system.
-	 */
-	lixcol_file_id: LixGenerated<string>;
-
-	/**
-	 * Plugin identifier that manages this entity type.
-	 *
-	 * This identifies which plugin is responsible for this entity's behavior
-	 * and schema definition.
-	 */
-	lixcol_plugin_key: LixGenerated<string>;
-
-	/**
-	 * Version of the schema used for this entity at this point in history.
-	 *
-	 * Format: "major.minor" (e.g., "1.0", "2.1")
-	 * This allows tracking schema evolution over time.
-	 */
-	lixcol_schema_version: LixGenerated<string>;
-
-	/**
-	 * ID of the change that created this specific entity state.
-	 *
-	 * Each modification to an entity creates a new change, and this ID
-	 * references that specific change in the change table.
-	 */
-	lixcol_change_id: LixGenerated<string>;
-
-	/**
-	 * Commit ID that serves as the query root for depth calculation.
-	 *
-	 * When querying history, this represents the "perspective" from which
-	 * you're viewing the entity's history. The depth is calculated relative
-	 * to this commit.
-	 */
-	lixcol_commit_id: LixGenerated<string>;
-
-	/**
-	 * The root commit ID used as the starting point for traversing history.
-	 *
-	 * When querying history from a specific commit, this field contains that
-	 * commit ID for all returned rows. Used with `depth` to understand how
-	 * far back in history each entity state is from this root.
-	 */
-	lixcol_root_commit_id: LixGenerated<string>;
-
-	/**
-	 * Depth of this entity state relative to the queried commit_id.
-	 *
-	 * - `0`: The entity state at the exact queried commit
-	 * - `1`: The entity state one commit before the queried commit
-	 * - `2+`: Earlier states, going back in history
-	 *
-	 * This is useful for blame functionality and understanding how an entity
-	 * evolved to reach its current state.
-	 */
-	lixcol_depth: LixGenerated<number>;
-
-	/**
-	 * Arbitrary metadata attached to the change that produced this historical state.
-	 */
-	lixcol_metadata: LixGenerated<Record<string, any> | null>;
-};

package/src/engine/entity-views/entity-state.ts

@@ -1,239 +0,0 @@
-import type { Generated } from "kysely";
-import type { LixGenerated } from "../../schema-definition/definition.js";
-/**
- * Base type for regular entity views (active version only) that include operational columns from the state table.
- * These views do NOT expose lixcol_version_id to prevent accidental version-specific operations.
- *
- * @example
- * ```typescript
- * // Define an entity view type for active version operations
- * export type AccountView = {
- *   id: Generated<string>;
- *   name: string;
- * } & StateEntityView;
- * ```
- */
-export type StateEntityView = {
-	/**
-	 * The unique identifier for this entity within its schema and file.
-	 *
-	 * This is the primary identifier used to reference this specific entity.
-	 */
-	lixcol_entity_id: Generated<string>;
-
-	/**
-	 * The schema key that defines the structure and type of this entity.
-	 *
-	 * This references the schema definition that validates and types this entity.
-	 */
-	lixcol_schema_key: Generated<string>;
-
-	/**
-	 * File identifier where this entity is stored.
-	 *
-	 * This references the file_id in the state table and links the entity
-	 * to a specific file in the Lix file system.
-	 */
-	lixcol_file_id: Generated<string>;
-
-	/**
-	 * The plugin key that manages this entity type.
-	 *
-	 * This identifies which plugin is responsible for handling this entity.
-	 */
-	lixcol_plugin_key: Generated<string>;
-
-	/**
-	 * Version identifier this entity was inherited from during branching.
-	 *
-	 * - `null` if the entity was created in the current version
-	 * - Contains the source version_id if the entity was inherited from another version
-	 *
-	 * This is useful for tracking entity lineage across version branches.
-	 */
-	lixcol_inherited_from_version_id: Generated<string | null>;
-
-	/**
-	 * Timestamp when this entity was created in the current version.
-	 *
-	 * **Important**: This timestamp is relative to the version, not global.
-	 * - When an entity is first created, this is the actual creation time
-	 * - When an entity is inherited from another version, this is the time it was inherited
-	 *
-	 * Format: ISO 8601 string (e.g., "2024-03-20T10:30:00.000Z")
-	 */
-	lixcol_created_at: Generated<string>;
-
-	/**
-	 * Timestamp when this entity was last updated in the current version.
-	 *
-	 * **Important**: This timestamp is relative to the version, not global.
-	 * - Updates only when the entity is modified within the current version
-	 * - When first inherited, this equals lixcol_created_at
-	 *
-	 * Format: ISO 8601 string (e.g., "2024-03-20T10:30:00.000Z")
-	 */
-	lixcol_updated_at: Generated<string>;
-
-	/**
-	 * Change identifier for the last modification to this entity.
-	 *
-	 * This references the change.id that last modified this entity, enabling
-	 * blame and diff functionality. Useful for tracking who made changes
-	 * and when they were made.
-	 */
-	lixcol_change_id: Generated<string>;
-
-	/**
-	 * Whether this entity is stored as untracked state.
-	 *
-	 * - `false` (default): Entity follows normal change control and versioning
-	 * - `true`: Entity bypasses change control for UI state, temporary data, etc.
-	 *
-	 * Untracked entities don't create change records and have highest priority
-	 * in the state resolution order: untracked > tracked > inherited.
-	 */
-	lixcol_untracked: Generated<boolean>;
-
-	/**
-	 * Commit identifier that contains this entity's last change.
-	 *
-	 * This references the commit.id that contains the last change to this entity.
-	 * Useful for understanding which commit a particular entity state belongs to,
-	 * enabling history queries and version comparison.
-	 */
-	lixcol_commit_id: Generated<string>;
-
-	/**
-	 * Writer key associated with the last mutation that produced this entity state.
-	 *
-	 * Used to attribute writes to individual clients/sessions for echo suppression.
-	 * Null when no writer key was set for the mutation.
-	 */
-	lixcol_writer_key: Generated<string | null>;
-};
-
-/**
- * Base type for regular entity views (active version only) that include operational columns from the state table.
- * These views do NOT expose lixcol_version_id to prevent accidental version-specific operations.
- *
- * This type uses LixGenerated markers instead of Kysely's Generated type, making it compatible
- * with the Lix SDK's type transformation system.
- *
- * @example
- * ```typescript
- * // Define an entity view type for active version operations
- * export type AccountView = {
- *   id: LixGenerated<string>;
- *   name: string;
- * } & EntityStateColumns;
- * ```
- */
-export type EntityStateColumns = {
-	/**
-	 * The unique identifier for this entity within its schema and file.
-	 *
-	 * This is the primary identifier used to reference this specific entity.
-	 */
-	lixcol_entity_id: LixGenerated<string>;
-
-	/**
-	 * The schema key that defines the structure and type of this entity.
-	 *
-	 * This references the schema definition that validates and types this entity.
-	 */
-	lixcol_schema_key: LixGenerated<string>;
-
-	/**
-	 * File identifier where this entity is stored.
-	 *
-	 * This references the file_id in the state table and links the entity
-	 * to a specific file in the Lix file system.
-	 */
-	lixcol_file_id: LixGenerated<string>;
-
-	/**
-	 * The plugin key that manages this entity type.
-	 *
-	 * This identifies which plugin is responsible for handling this entity.
-	 */
-	lixcol_plugin_key: LixGenerated<string>;
-
-	/**
-	 * Version identifier this entity was inherited from during branching.
-	 *
-	 * - `null` if the entity was created in the current version
-	 * - Contains the source version_id if the entity was inherited from another version
-	 *
-	 * This is useful for tracking entity lineage across version branches.
-	 */
-	lixcol_inherited_from_version_id: LixGenerated<string | null>;
-
-	/**
-	 * Timestamp when this entity was created in the current version.
-	 *
-	 * **Important**: This timestamp is relative to the version, not global.
-	 * - When an entity is first created, this is the actual creation time
-	 * - When an entity is inherited from another version, this is the time it was inherited
-	 *
-	 * Format: ISO 8601 string (e.g., "2024-03-20T10:30:00.000Z")
-	 */
-	lixcol_created_at: LixGenerated<string>;
-
-	/**
-	 * Timestamp when this entity was last updated in the current version.
-	 *
-	 * **Important**: This timestamp is relative to the version, not global.
-	 * - Updates only when the entity is modified within the current version
-	 * - When first inherited, this equals lixcol_created_at
-	 *
-	 * Format: ISO 8601 string (e.g., "2024-03-20T10:30:00.000Z")
-	 */
-	lixcol_updated_at: LixGenerated<string>;
-
-	/**
-	 * Change identifier for the last modification to this entity.
-	 *
-	 * This references the change.id that last modified this entity, enabling
-	 * blame and diff functionality. Useful for tracking who made changes
-	 * and when they were made.
-	 */
-	lixcol_change_id: LixGenerated<string>;
-
-	/**
-	 * Whether this entity is stored as untracked state.
-	 *
-	 * - `false` (default): Entity follows normal change control and versioning
-	 * - `true`: Entity bypasses change control for UI state, temporary data, etc.
-	 *
-	 * Untracked entities don't create change records and have highest priority
-	 * in the state resolution order: untracked > tracked > inherited.
-	 */
-	lixcol_untracked: LixGenerated<boolean>;
-
-	/**
-	 * Commit identifier that contains this entity's last change.
-	 *
-	 * This references the commit.id that contains the last change to this entity.
-	 * Useful for understanding which commit a particular entity state belongs to,
-	 * enabling history queries and version comparison.
-	 */
-	lixcol_commit_id: LixGenerated<string>;
-
-	/**
-	 * Writer key associated with the last mutation that produced this entity state.
-	 *
-	 * Used to attribute writes to individual clients/sessions for echo suppression.
-	 * Null when no writer key was set for the mutation.
-	 */
-	lixcol_writer_key: LixGenerated<string | null>;
-
-	/**
-	 * Arbitrary metadata attached to the change that produced this entity state.
-	 *
-	 * This is sourced from the metadata stored alongside the originating change
-	 * and allows callers to attach additional contextual information without
-	 * modifying the entity schema.
-	 */
-	lixcol_metadata: LixGenerated<Record<string, any> | null>;
-};