@ekairos/domain 1.21.0 → 1.21.3-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekairos/domain",
-  "version": "1.21.0",
+  "version": "1.21.3-beta.0",
   "description": "Pulzar Domain Utilities",
   "type": "commonjs",
   "main": "dist/index.js",
@@ -35,6 +35,9 @@
   "dependencies": {
     "@instantdb/core": "latest"
   },
+  "peerDependencies": {
+    "@instantdb/admin": "*"
+  },
   "devDependencies": {
     "@ekairos/tsconfig": "workspace:*",
     "@types/node": "^24.5.0",

package/dist/__type_tests__/domain-builder.typecheck.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=domain-builder.typecheck.d.ts.map

package/dist/__type_tests__/domain-builder.typecheck.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"domain-builder.typecheck.d.ts","sourceRoot":"","sources":["../../src/__type_tests__/domain-builder.typecheck.ts"],"names":[],"mappings":""}

package/dist/__type_tests__/domain-builder.typecheck.js

@@ -1,660 +0,0 @@
-"use strict";
-// Type tests for domain builder with dependsOn
-// These should fail initially, then pass after implementation
-Object.defineProperty(exports, "__esModule", { value: true });
-const __1 = require("..");
-const core_1 = require("@instantdb/core");
-// Base entities ($users, $files) are automatically included by domain builder
-// Core domain (hosts organizations)
-const otherDomain = (0, __1.domain)({
-    entities: {
-        organizations: core_1.i.entity({
-            clerkOrgId: core_1.i.string().indexed().unique(),
-            timezone: core_1.i.string().optional(),
-        }),
-    },
-    links: {},
-    rooms: {},
-});
-// OK: cross-domain links after includes (runtime automatically merges entities)
-const management = (0, __1.domain)("management")
-    .includes(otherDomain)
-    .schema({
-    entities: {
-        management_projects: core_1.i.entity({
-            name: core_1.i.string(),
-            createdAt: core_1.i.date(),
-            updatedAt: core_1.i.date(),
-            description: core_1.i.string().optional(),
-            linearProjectId: core_1.i.string().optional(),
-        }),
-        management_tasks: core_1.i.entity({
-            title: core_1.i.string(),
-            status: core_1.i.string(),
-            createdAt: core_1.i.date(),
-            updatedAt: core_1.i.date(),
-            description: core_1.i.string().optional(),
-        }),
-    },
-    links: {
-        management_projectsOrganization: {
-            forward: { on: "management_projects", has: "one", label: "organization" },
-            reverse: { on: "organizations", has: "many", label: "management_projects" },
-        },
-        management_tasksUser: {
-            forward: { on: "management_tasks", has: "one", label: "assignee" },
-            reverse: { on: "$users", has: "many", label: "management_tasks" },
-        },
-    },
-    rooms: {},
-});
-// OK: link only to base entities ($users/$files) without deps
-const filesOnly = (0, __1.domain)("filesOnly").schema({
-    entities: {
-        assets: core_1.i.entity({
-            name: core_1.i.string(),
-        }),
-    },
-    links: {
-        assetsFiles: {
-            forward: { on: "assets", has: "many", label: "$files" },
-            reverse: { on: "$files", has: "one", label: "asset" },
-        },
-    },
-    rooms: {},
-});
-// Note: Cross-domain link validation is now runtime-only for simplicity
-// The domain builder automatically includes base entities and merges included domains
-const runtimeValidatedExample = (0, __1.domain)("management")
-    .includes(otherDomain)
-    .schema({
-    entities: {
-        management_projects: core_1.i.entity({
-            name: core_1.i.string(),
-        }),
-        management_tasks: core_1.i.entity({
-            title: core_1.i.string(),
-        }),
-    },
-    links: {
-        // This will work because runtime merges in organizations from otherDomain
-        management_projectsOrganization: {
-            forward: { on: "management_projects", has: "one", label: "organization" },
-            reverse: { on: "organizations", has: "many", label: "management_projects" },
-        },
-        // Base entities are automatically available
-        management_tasksUser: {
-            forward: { on: "management_tasks", has: "one", label: "assignee" },
-            reverse: { on: "$users", has: "many", label: "management_tasks" },
-        },
-    },
-    rooms: {},
-});
-// OK: Base entities are automatically available without explicit declaration
-const baseEntitiesOnly = (0, __1.domain)("baseTest").schema({
-    entities: {
-        test_entity: core_1.i.entity({
-            name: core_1.i.string(),
-        }),
-    },
-    links: {
-        testEntityFiles: {
-            forward: { on: "test_entity", has: "many", label: "$files" },
-            reverse: { on: "$files", has: "one", label: "test_entity" },
-        },
-        testEntityUsers: {
-            forward: { on: "test_entity", has: "one", label: "owner" },
-            reverse: { on: "$users", has: "many", label: "owned_entities" },
-        },
-    },
-    rooms: {},
-});
-// Example usage of includes method
-const coreDomain = (0, __1.domain)({
-    entities: {
-        organizations: core_1.i.entity({
-            clerkOrgId: core_1.i.string().indexed().unique(),
-            timezone: core_1.i.string().optional(),
-        }),
-    },
-    links: {},
-    rooms: {},
-});
-const managementDomain = (0, __1.domain)("management")
-    .includes(coreDomain) // Include entities from coreDomain for cross-references
-    .schema({
-    entities: {
-        management_projects: core_1.i.entity({
-            name: core_1.i.string(),
-            createdAt: core_1.i.date(),
-            updatedAt: core_1.i.date(),
-        }),
-        management_tasks: core_1.i.entity({
-            title: core_1.i.string(),
-            status: core_1.i.string(),
-            createdAt: core_1.i.date(),
-            updatedAt: core_1.i.date(),
-        }),
-    },
-    links: {
-        // Can reference organizations from included coreDomain
-        management_projectsOrganization: {
-            forward: { on: "management_projects", has: "one", label: "organization" },
-            reverse: { on: "organizations", has: "many", label: "management_projects" },
-        },
-        // Can reference base entities ($users, $files) automatically
-        management_tasksUser: {
-            forward: { on: "management_tasks", has: "one", label: "assignee" },
-            reverse: { on: "$users", has: "many", label: "management_tasks" },
-        },
-    },
-    rooms: {},
-});
-// Flat schema construction - when spreading directly into i.schema, include base entities
-// Note: managementDomain.links may reference entities that will be available after includes ($users, cross-domain)
-// Links reference $users which will be available when base entities are merged
-// Use toInstantSchema() to get the properly typed schema with all entities and links merged
-const baseForFlat = core_1.i.schema({ entities: {}, links: {}, rooms: {} });
-const managementSchema = managementDomain.toInstantSchema();
-const completeSchema = core_1.i.schema({
-    entities: {
-        ...baseForFlat.entities,
-        ...managementSchema.entities, // Includes base + core + management entities
-    },
-    links: managementSchema.links, // Links from toInstantSchema include all merged links
-    rooms: {
-        ...managementSchema.rooms,
-    },
-});
-// Test compose still works with domain instances
-const classicDomain = (0, __1.domain)({
-    entities: { test: core_1.i.entity({ name: core_1.i.string() }) },
-    links: {},
-    rooms: {},
-});
-const composed = classicDomain.compose((0, __1.domain)({
-    entities: { other: core_1.i.entity({ value: core_1.i.number() }) },
-    links: {},
-    rooms: {},
-}));
-// Test: Domain builder produces flat objects compatible with i.schema
-// This demonstrates the flat approach - domains return plain objects
-const managementEntities = management.entities;
-const managementLinks = management.links;
-const filesOnlyEntities = filesOnly.entities;
-// These can be spread directly into i.schema in real usage
-const _entities = managementEntities;
-const _links = managementLinks;
-// Type assertions for runtime verification (these should not fail)
-const _management = management;
-const _filesOnly = filesOnly;
-const _composed = composed;
-// Test toInstantSchema method compatibility
-const domainWithInstantSchema = (0, __1.domain)("instantTest")
-    .includes(otherDomain)
-    .schema({
-    entities: {
-        instant_entities: core_1.i.entity({
-            name: core_1.i.string(),
-        }),
-    },
-    links: {
-        instantEntityOrg: {
-            forward: { on: "instant_entities", has: "one", label: "organization" },
-            reverse: { on: "organizations", has: "many", label: "instant_entities" },
-        },
-    },
-    rooms: {},
-});
-const _instantSchemaCheck = true;
-// =====================================================================================
-// Test: Links from included domains are merged into final schema
-// =====================================================================================
-// Domain with links that should be included
-const domainWithLinks = (0, __1.domain)("withLinks").schema({
-    entities: {
-        included_entities: core_1.i.entity({
-            name: core_1.i.string(),
-        }),
-    },
-    links: {
-        includedLink: {
-            forward: { on: "included_entities", has: "one", label: "owner" },
-            reverse: { on: "$users", has: "many", label: "owned_included_entities" },
-        },
-    },
-    rooms: {},
-});
-// Domain that includes the above domain
-const domainIncludingLinks = (0, __1.domain)("including")
-    .includes(domainWithLinks)
-    .schema({
-    entities: {
-        including_entities: core_1.i.entity({
-            title: core_1.i.string(),
-        }),
-    },
-    links: {
-        includingLink: {
-            forward: { on: "including_entities", has: "one", label: "creator" },
-            reverse: { on: "$users", has: "many", label: "created_entities" },
-        },
-    },
-    rooms: {},
-});
-// Verify that links from included domain are present in the final schema
-const finalSchemaIncludingLinks = domainIncludingLinks.toInstantSchema();
-// Runtime check: both links should be present
-const hasIncludedLink = "includedLink" in finalSchemaIncludingLinks.links;
-const hasIncludingLink = "includingLink" in finalSchemaIncludingLinks.links;
-const _linksMergedCheck1 = true;
-const _linksMergedCheck2 = true;
-// =====================================================================================
-// Test: db.query can use links from included domains
-// =====================================================================================
-// Domain with a link that should be queryable
-const domainWithQueryableLink = (0, __1.domain)("withQueryable").schema({
-    entities: {
-        queryable_entities: core_1.i.entity({
-            name: core_1.i.string(),
-        }),
-    },
-    links: {
-        queryableLink: {
-            forward: { on: "queryable_entities", has: "one", label: "owner" },
-            reverse: { on: "$users", has: "many", label: "owned_queryable_entities" },
-        },
-    },
-    rooms: {},
-});
-// Domain that includes the above and adds its own entities/links
-const domainWithIncludedQueryableLink = (0, __1.domain)("withIncluded")
-    .includes(domainWithQueryableLink)
-    .schema({
-    entities: {
-        local_entities: core_1.i.entity({
-            title: core_1.i.string(),
-        }),
-    },
-    links: {
-        localLink: {
-            forward: { on: "local_entities", has: "one", label: "creator" },
-            reverse: { on: "$users", has: "many", label: "created_local_entities" },
-        },
-    },
-    rooms: {},
-});
-// Create schema and verify query structure accepts links from included domain
-const queryableSchema = domainWithIncludedQueryableLink.toInstantSchema();
-const _queryableLinkCheck = true;
-const _localLinkCheck = true;
-// Runtime verification: schema should have both links
-const hasQueryableLinkRuntime = "queryableLink" in queryableSchema.links;
-const hasLocalLinkRuntime = "localLink" in queryableSchema.links;
-// These should both be true if links are properly merged
-if (!hasQueryableLinkRuntime || !hasLocalLinkRuntime) {
-    throw new Error("Links from included domains are not present in final schema");
-}
-// =====================================================================================
-// Test: db.query structure with link traversal from included domains
-// =====================================================================================
-// Domain with entities and links that enable link traversal queries
-const domainWithLinkTraversal = (0, __1.domain)("withLinkTraversal").schema({
-    entities: {
-        organization_users: core_1.i.entity({
-            firstName: core_1.i.string().optional(),
-            lastName: core_1.i.string().optional(),
-        }),
-    },
-    links: {
-        usersUserUsers: {
-            forward: { on: "organization_users", has: "one", label: "identity" },
-            reverse: { on: "$users", has: "many", label: "user_users" },
-        },
-    },
-    rooms: {},
-});
-// Domain that includes the above
-const domainIncludingLinkTraversal = (0, __1.domain)("includingTraversal")
-    .includes(domainWithLinkTraversal)
-    .schema({
-    entities: {
-        local_items: core_1.i.entity({
-            name: core_1.i.string(),
-        }),
-    },
-    links: {},
-    rooms: {},
-});
-// Create schema for query testing
-const traversalSchema = domainIncludingLinkTraversal.toInstantSchema();
-const _traversalLinkCheck = true;
-// Runtime check: link should be present
-const hasTraversalLink = "usersUserUsers" in traversalSchema.links;
-if (!hasTraversalLink) {
-    throw new Error("Link from included domain not available for query traversal");
-}
-// =====================================================================================
-// Test: InstantDB utility types work with merged schemas from included domains
-// =====================================================================================
-// Create a comprehensive test schema with multiple domains and links
-const testDomainA = (0, __1.domain)("testA").schema({
-    entities: {
-        test_a_items: core_1.i.entity({
-            name: core_1.i.string(),
-            value: core_1.i.number(),
-        }),
-    },
-    links: {
-        testAItemsOwner: {
-            forward: { on: "test_a_items", has: "one", label: "owner" },
-            reverse: { on: "$users", has: "many", label: "owned_test_a_items" },
-        },
-    },
-    rooms: {},
-});
-// testDomainB includes testDomainA to reference test_a_items in links
-// This ensures type safety: links can only reference entities that are available
-const testDomainB = (0, __1.domain)("testB")
-    .includes(testDomainA)
-    .schema({
-    entities: {
-        test_b_items: core_1.i.entity({
-            title: core_1.i.string(),
-            status: core_1.i.string(),
-        }),
-    },
-    links: {
-        testBItemsCreator: {
-            forward: { on: "test_b_items", has: "one", label: "creator" },
-            reverse: { on: "$users", has: "many", label: "created_test_b_items" },
-        },
-        testBItemsRelated: {
-            forward: { on: "test_b_items", has: "one", label: "related" },
-            reverse: { on: "test_a_items", has: "many", label: "test_b_items" },
-        },
-    },
-    rooms: {},
-});
-// Combined schema with both domains
-const combinedTestSchema = (0, __1.domain)("combined")
-    .includes(testDomainA)
-    .includes(testDomainB)
-    .schema({
-    entities: {
-        combined_items: core_1.i.entity({
-            description: core_1.i.string(),
-        }),
-    },
-    links: {
-        combinedItemsParent: {
-            forward: { on: "combined_items", has: "one", label: "parent" },
-            reverse: { on: "test_b_items", has: "many", label: "combined_items" },
-        },
-    },
-    rooms: {},
-});
-// Note: $users is added at runtime, so it may not be in compile-time type
-// We verify it exists at runtime in Test 9
-const _entityCheck1 = true;
-const _entityCheck2 = true;
-const _entityCheck3 = true;
-const _linkCheck1 = true;
-const _linkCheck2 = true;
-const _linkCheck3 = true;
-const _linkCheck4 = true;
-// Test 3: InstaQLParams - Query typechecking with links from included domains
-// Note: TypeScript's type system may not fully recognize merged links from included domains
-// at compile time, but they work correctly at runtime (verified in Test 9)
-const queryWithIncludedLinks = {
-    test_a_items: {
-        owner: {},
-    },
-    test_b_items: {
-        creator: {},
-        related: {
-            owner: {},
-        },
-    },
-    combined_items: {
-        parent: {
-            creator: {},
-            related: {},
-        },
-    },
-};
-// Test 4: InstaQLParams - Query with link traversal from included domain
-// Note: Using 'as' because merged links from included domains aren't in compile-time types
-// but work correctly at runtime. See Test 4b for validation demonstration.
-const queryWithLinkTraversal = {
-    test_a_items: {
-        $: {
-            where: { "owner.email": "test@example.com" },
-        },
-        owner: {},
-    },
-};
-// Test 4b: Validation test - demonstrates that satisfies catches invalid properties
-// Using a single domain (no includes) so types are complete and validation works
-const validationTestDomain = (0, __1.domain)("validationTest").schema({
-    entities: {
-        validation_items: core_1.i.entity({
-            name: core_1.i.string(),
-        }),
-    },
-    links: {
-        validationItemsOwner: {
-            forward: { on: "validation_items", has: "one", label: "owner" },
-            reverse: { on: "$users", has: "many", label: "validation_items" },
-        },
-    },
-    rooms: {},
-});
-// This validates correctly - valid query
-const validQuery = {
-    validation_items: {
-        owner: {},
-    },
-};
-const _invalidQueryTypoCheck = true; // Should be true (not assignable)
-const _validQueryCheck = true; // Should be true (assignable)
-// This would fail validation - invalid property 'x'
-// Uncomment to see TypeScript error:
-// const invalidQuery = {
-//   validation_items: {
-//     x: {},  // Error: 'x' does not exist
-//   },
-// } satisfies InstaQLParams<ValidationSchema>;
-// Test 5: InstaQLParams - Query with all entities from included domains
-const queryAllEntities = {
-    test_a_items: {},
-    test_b_items: {
-        related: {},
-    },
-    combined_items: {
-        parent: {},
-    },
-    $users: {},
-};
-// Test 6: InstaQLParams - Query using link traversal across included domains
-const queryCrossDomainTraversal = {
-    test_b_items: {
-        $: {
-            where: { "related.owner.email": "test@example.com" },
-        },
-        related: {
-            owner: {},
-        },
-    },
-};
-// Test 9: Runtime verification - schema should have all entities and links
-const finalSchema = combinedTestSchema.toInstantSchema();
-const hasTestAItems = "test_a_items" in finalSchema.entities;
-const hasTestBItems = "test_b_items" in finalSchema.entities;
-const hasCombinedItems = "combined_items" in finalSchema.entities;
-const hasUsers = "$users" in finalSchema.entities;
-const hasTestAItemsOwnerLink = "testAItemsOwner" in finalSchema.links;
-const hasTestBItemsCreatorLink = "testBItemsCreator" in finalSchema.links;
-const hasTestBItemsRelatedLink = "testBItemsRelated" in finalSchema.links;
-const hasCombinedItemsParentLink = "combinedItemsParent" in finalSchema.links;
-if (!hasTestAItems || !hasTestBItems || !hasCombinedItems || !hasUsers) {
-    throw new Error("Not all entities from included domains are present in final schema");
-}
-if (!hasTestAItemsOwnerLink || !hasTestBItemsCreatorLink || !hasTestBItemsRelatedLink || !hasCombinedItemsParentLink) {
-    throw new Error("Not all links from included domains are present in final schema");
-}
-// Note: In a real application with @instantdb/react or @instantdb/admin installed,
-// you would use the utility types like this:
-//
-// import type { InstaQLParams, InstaQLResult, InstaQLEntity } from "@instantdb/react";
-//
-// const query = {
-//   test_a_items: { owner: {} },
-//   test_b_items: { creator: {}, related: { owner: {} } },
-// } satisfies InstaQLParams<CombinedSchema>;
-//
-// type Result = InstaQLResult<CombinedSchema, typeof query>;
-// type Item = InstaQLEntity<CombinedSchema, "test_a_items", { owner: {} }>;
-// =====================================================================================
-// Test: Compare InstantDB pure schema vs domain schema for InstaQLParams validation
-// =====================================================================================
-// Pure InstantDB schema - this should work correctly with InstaQLParams
-const pureInstantSchema = core_1.i.schema({
-    entities: {
-        test_items: core_1.i.entity({
-            name: core_1.i.string(),
-        }),
-        $users: core_1.i.entity({
-            email: core_1.i.string().optional().indexed(),
-        }),
-    },
-    links: {
-        testItemsOwner: {
-            forward: { on: "test_items", has: "one", label: "owner" },
-            reverse: { on: "$users", has: "many", label: "test_items" },
-        },
-    },
-    rooms: {},
-});
-// Test pure schema validation - this should work
-const pureValidQuery = {
-    test_items: {
-        owner: {},
-    },
-};
-// This should fail with pure schema
-// Uncomment to see TypeScript error:
-// const pureInvalidQuery = {
-//   test_items: {
-//     ownexr: {},  // Error: 'ownexr' does not exist
-//   },
-// } satisfies InstaQLParams<PureInstantSchema>;
-// Domain schema - should behave the same as pure schema
-const domainTestSchema = (0, __1.domain)("domainTest").schema({
-    entities: {
-        test_items: core_1.i.entity({
-            name: core_1.i.string(),
-        }),
-    },
-    links: {
-        testItemsOwner: {
-            forward: { on: "test_items", has: "one", label: "owner" },
-            reverse: { on: "$users", has: "many", label: "test_items" },
-        },
-    },
-    rooms: {},
-});
-// Test domain schema validation - should work the same as pure schema
-const domainValidQuery = {
-    test_items: {
-        owner: {},
-    },
-};
-const _domainInvalidQueryCheck = true; // Should be true (not assignable)
-const _domainValidQueryCheck = true; // Should be true (assignable)
-// These may be false due to type inference, but InstaQLParams validation works correctly
-// The important test is that invalid queries are rejected (verified above)
-const _pureLinkCheck = false; // May be false, but validation works
-const _domainLinkCheck = false; // May be false, but validation works
-// These should be the literal type "owner"
-const _pureLabelCheck = "owner";
-const _domainLabelCheck = "owner";
-// These may be false due to type inference, but InstaQLParams validation works correctly
-// The critical test is that invalid queries are rejected (verified above)
-const _pureEntityEnrichment = false; // May be false, but validation works
-const _domainEntityEnrichment = false; // May be false, but validation works
-// =====================================================================================
-// Test: Verify that attribute validation works in queries with link traversal
-// =====================================================================================
-// Pure InstantDB schema for attribute validation testing
-const pureAttrSchema = core_1.i.schema({
-    entities: {
-        test_items: core_1.i.entity({
-            name: core_1.i.string(),
-            value: core_1.i.number(),
-        }),
-        $users: core_1.i.entity({
-            email: core_1.i.string().optional().indexed(),
-            name: core_1.i.string().optional(),
-        }),
-    },
-    links: {
-        testItemsOwner: {
-            forward: { on: "test_items", has: "one", label: "owner" },
-            reverse: { on: "$users", has: "many", label: "test_items" },
-        },
-    },
-    rooms: {},
-});
-// Valid query with valid attribute - should work
-const pureValidAttrQuery = {
-    test_items: {
-        $: {
-            where: { "oasdwner.email": "test@example.com" }, // Valid: email exists on $users
-        },
-        owner: {},
-    },
-};
-// Current behavior: false (assignable) - InstantDB doesn't validate attributes in where
-const _pureInvalidAttrCheck = false; // InstantDB 0.22.48 doesn't validate attributes
-const _pureValidAttrCheck = true; // Should be true (assignable)
-// Domain schema for attribute validation testing
-const domainAttrSchema = (0, __1.domain)("domainAttrTest").schema({
-    entities: {
-        test_items: core_1.i.entity({
-            name: core_1.i.string(),
-            value: core_1.i.number(),
-        }),
-    },
-    links: {
-        testItemsOwner: {
-            forward: { on: "test_items", has: "one", label: "owner" },
-            reverse: { on: "$users", has: "many", label: "test_items" },
-        },
-    },
-    rooms: {},
-});
-// Valid query with valid attribute - should work
-const domainValidAttrQuery = {
-    test_items: {
-        $: {
-            where: { "owner.email": "test@example.com" }, // Valid: email exists on $users
-        },
-        owner: {},
-    },
-};
-// TODO: Fix toInstantSchema() return type to preserve entity attribute types
-// Currently false (assignable) but should be true (not assignable)
-const _domainInvalidAttrCheck = false; // BUG: Should be true but currently false
-const _domainValidAttrCheck = true; // Should be true (assignable)
-// Current behavior: false (assignable) - InstantDB doesn't validate attributes in where
-const _pureInvalidEntityAttrCheck = false; // InstantDB 0.22.48 doesn't validate attributes
-// TODO: Fix toInstantSchema() return type to preserve entity attribute types
-// Currently false (assignable) but should be true (not assignable)
-const _domainInvalidEntityAttrCheck = false; // BUG: Should be true but currently false
-// =====================================================================================
-// ❌ COMPILE-TIME VALIDATION: Links and Entity Conflicts
-// =====================================================================================
-// (Omitted negative tests that intentionally fail compilation)
-// (Known limitation) Duplicate entity names across includes are not detected at compile time
-//# sourceMappingURL=domain-builder.typecheck.js.map