koota 0.0.3 → 0.0.5

package/README.md

@@ -318,15 +318,22 @@ const time = world.get(Time);
 world.set(Time, { current: performance.now() });
 ```
 
+### Select traits on queries for updates
+Query filters entity results and `select` is used to choose what traits are fetched for `updateEach` and `useStore`.
+
+```js
+// Add example when I get the energy
+```
+
 ### Modifying trait stores direclty
 
 For performance-critical operations, you can modify trait stores directly using the useStore hook. This approach bypasses some of the safety checks and event triggers, so use it with caution. All stores are structure of arrays for performance purposes.
 
 ```js
 // Returns the SoA stores
-world.query(Position, Velocity).useStore(([position, store], entities) => {
+world.query(Position, Velocity).useStore(([position, velocity], entities) => {
     // Write our own loop over the stores
-    for (let i = 0; i > entities.length; i++) {
+    for (let i = 0; i < entities.length; i++) {
         // Get the entity ID to use as the array index
         const eid = entities[i].id();
         // Write to each array in the store
@@ -335,3 +342,127 @@ world.query(Position, Velocity).useStore(([position, store], entities) => {
     }
 });
 ```
+
+## APIs in detail until I make docs
+
+These are more like notes for docs. Take a look around, ask questions. Eventually this will become proper docs.
+
+### World
+
+This is where all data is stored. We have methods on entities but this is a bit of a trick, entities don't actually store any data and instead it is operating on the connected world. Each world has its own set of entities that do not overlap with another. Typically you only need one world.
+
+Worlds can have traits, which is our version of a singleton. Use these for global resources like a clock. Each world gets its own entity used for world traits. This entity is no queryable but will show up in the list of active entities making the only way to retrieve a world trait with its API.
+
+```js
+// Spawns an entity
+// Can pass any number of traits
+// Return Entity
+const entity = world.spawn()
+
+// Checks if the world has the entity
+// Return boolean
+const result = world.has(entity)
+
+// Get all entities that match the query parameters
+// Return QueryResult (which is Entity[] with extras)
+const entities = world.query(Position)
+
+// Return the first entity that matches the query
+// Return Entity
+const entity = world.queryFirst(Position)
+
+// The trait API is identical to entity's
+
+// Add a trait to the world
+world.add(Time)
+
+// Remove a trait from the world
+world.remove(Time)
+
+// Check if the world has a trait
+// Return boolean
+const result = world.has(Time)
+
+// Gets a snapshot instance of the trait
+// Return TraitInstance
+const time = world.get(Time)
+
+// Sets the trait and triggers a change event
+world.set(Time, { current: performance.now() })
+
+// Subscribe to add, remove or change events for a set of query parameters
+// Anything you can put in a query is legal
+// Return unsub function
+const unsub = world.onAdd([Position], (entity) => {})
+const unsub = world.onRemove([Position], (entity) => {})
+const unsub = world.onChange([Position], (entity) => {})
+
+// An array of all entities alive in the world
+// This is a copy so editing it won't do anything!
+// Entity[]
+world.entities
+
+// Returns the world's unique ID
+// Return number
+const id = world.id()
+
+// Resets the world as if it were just created
+world.reset()
+
+// Nukes the world and releases its ID
+world.destroy()
+```
+
+### Entity
+
+An entity is a number encoded with a world, generation and ID. Every entity is unique even if they have the same ID since they will have different generations. This makes automatic-recycling possible without reference errors. Because of this, the number of an entity won't give you its ID but will have to instaed be decoded with `entity.id()`.
+
+```js
+// Add a trait to the entity
+entity.add(Position) 
+
+// Remove a trait from the entity
+entity.remove(Position)
+
+// Checks if the entity has the trait
+// Return boolean
+const result = enttiy.has(Position) 
+
+// Gets a snapshot instance of the trait
+// Return TraitInstance
+const position = entity.get(Position)
+
+// Sets the trait and triggers a change event
+entity.set(Position, { x: 10, y: 10 })
+
+// Get the targets for a relationship
+// Return Entity[]
+const targets = entity.targetsFor(Contains)
+
+// Get the first target for a relationship
+// Return Entity
+const target = entity.targetFor(Contains)
+
+// Get the entity ID
+// Return number
+const id = entity.id()
+
+// Destroys the entity making its number no longer valid
+entity.destroy()
+```
+
+### React
+
+`useEntityRef` is a safe way to spawn an entity per React primitive and add traits. It is usually used for adding traits that capture the ref to the entity. The entity will be stable for the lifetime of the React component, except in cases like HMR.
+
+```js
+const Ref = trait({ value: null! })
+
+function Rocket() {
+    const entityRef = useEntityRef((node, entity) => {
+        entity.add(Ref({ value: node }))
+    })
+
+    return <div ref={entityRef}>🚀</div>
+}
+```

package/dist/index.cjs

@@ -297,10 +297,12 @@ function addTrait(world, entity, ...traits) {
         }
       }
     }
-    const defaults = data.schema;
-    for (const key in defaults) {
-      if (typeof defaults[key] === "function") {
-        defaults[key] = defaults[key]();
+    const defaults = {};
+    for (const key in data.schema) {
+      if (typeof data.schema[key] === "function") {
+        defaults[key] = data.schema[key]();
+      } else {
+        defaults[key] = data.schema[key];
       }
     }
     entity.set(trait2, { ...defaults, ...params }, false);
@@ -350,7 +352,6 @@ function hasTrait(world, entity, trait2) {
 }
 function getStore(world, trait2) {
   const ctx = world[$internal];
-  if (!ctx.traitData.has(trait2)) registerTrait(world, trait2);
   const data = ctx.traitData.get(trait2);
   const store = data.store;
   return store;

package/dist/index.js

@@ -258,10 +258,12 @@ function addTrait(world, entity, ...traits) {
         }
       }
     }
-    const defaults = data.schema;
-    for (const key in defaults) {
-      if (typeof defaults[key] === "function") {
-        defaults[key] = defaults[key]();
+    const defaults = {};
+    for (const key in data.schema) {
+      if (typeof data.schema[key] === "function") {
+        defaults[key] = data.schema[key]();
+      } else {
+        defaults[key] = data.schema[key];
       }
     }
     entity.set(trait2, { ...defaults, ...params }, false);
@@ -311,7 +313,6 @@ function hasTrait(world, entity, trait2) {
 }
 function getStore(world, trait2) {
   const ctx = world[$internal];
-  if (!ctx.traitData.has(trait2)) registerTrait(world, trait2);
   const data = ctx.traitData.get(trait2);
   const store = data.store;
   return store;

package/dist/react.cjs

@@ -22,13 +22,14 @@ var react_exports = {};
 __export(react_exports, {
   WorldProvider: () => WorldProvider,
   createActions: () => createActions,
+  useEntityRef: () => useEntityRef,
   useObserve: () => useObserve,
   useQuery: () => useQuery,
   useWorld: () => useWorld
 });
 module.exports = __toCommonJS(react_exports);
 
-// ../react/src/query/use-query.ts
+// ../react/src/hooks/use-query.ts
 var import_react3 = require("react");
 
 // ../react/src/world/use-world.ts
@@ -45,7 +46,7 @@ function useWorld() {
   return world;
 }
 
-// ../react/src/query/use-query.ts
+// ../react/src/hooks/use-query.ts
 function useQuery(...parameters) {
   const world = useWorld();
   const [entities, setEntities] = (0, import_react3.useState)([]);
@@ -83,7 +84,7 @@ function createActions(actionSet) {
   );
 }
 
-// ../react/src/trait/use-observe.tsx
+// ../react/src/hooks/use-observe.ts
 var import_react4 = require("react");
 function useObserve(entity, trait) {
   const world = useWorld();
@@ -101,10 +102,30 @@ function useObserve(entity, trait) {
   }, [entity, trait]);
   return value;
 }
+
+// ../react/src/hooks/use-entity-ref.ts
+var import_react5 = require("react");
+function useEntityRef(callback) {
+  const world = useWorld();
+  const entityRef = (0, import_react5.useRef)(null);
+  return (0, import_react5.useCallback)(
+    (node) => {
+      if (node) {
+        if (entityRef.current) entityRef.current.destroy();
+        entityRef.current = world.spawn();
+        callback(node, entityRef.current);
+      } else if (entityRef.current) {
+        entityRef.current.destroy();
+      }
+    },
+    [world]
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   WorldProvider,
   createActions,
+  useEntityRef,
   useObserve,
   useQuery,
   useWorld

package/dist/react.d.cts

@@ -1,7 +1,7 @@
-import { Q as QueryParameter, W as World, T as Trait, j as Entity, d as TraitInstanceFromSchema, E as ExtractSchema } from './world-BRz2NI5_.cjs';
+import { Q as QueryParameter, j as Entity, W as World, T as Trait, d as TraitInstanceFromSchema, E as ExtractSchema } from './world-BRz2NI5_.cjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
-declare function useQuery(...parameters: QueryParameter[]): number[];
+declare function useQuery(...parameters: QueryParameter[]): Entity[];
 
 declare function WorldProvider({ children, world }: {
     children: React.ReactNode;
@@ -16,4 +16,6 @@ declare function createActions<T extends Record<string, (...args: any[]) => any>
 
 declare function useObserve<T extends Trait>(entity: Entity, trait: T): TraitInstanceFromSchema<ExtractSchema<T>> | undefined;
 
-export { WorldProvider, createActions, useObserve, useQuery, useWorld };
+declare function useEntityRef<T = any>(callback: (node: T, entity: Entity) => void): (node: T) => void;
+
+export { WorldProvider, createActions, useEntityRef, useObserve, useQuery, useWorld };

package/dist/react.d.ts

@@ -1,7 +1,7 @@
-import { Q as QueryParameter, W as World, T as Trait, j as Entity, d as TraitInstanceFromSchema, E as ExtractSchema } from './world-BRz2NI5_.js';
+import { Q as QueryParameter, j as Entity, W as World, T as Trait, d as TraitInstanceFromSchema, E as ExtractSchema } from './world-BRz2NI5_.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
-declare function useQuery(...parameters: QueryParameter[]): number[];
+declare function useQuery(...parameters: QueryParameter[]): Entity[];
 
 declare function WorldProvider({ children, world }: {
     children: React.ReactNode;
@@ -16,4 +16,6 @@ declare function createActions<T extends Record<string, (...args: any[]) => any>
 
 declare function useObserve<T extends Trait>(entity: Entity, trait: T): TraitInstanceFromSchema<ExtractSchema<T>> | undefined;
 
-export { WorldProvider, createActions, useObserve, useQuery, useWorld };
+declare function useEntityRef<T = any>(callback: (node: T, entity: Entity) => void): (node: T) => void;
+
+export { WorldProvider, createActions, useEntityRef, useObserve, useQuery, useWorld };

package/dist/react.js

@@ -1,6 +1,6 @@
 import "./chunk-AQ5VUG5P.js";
 
-// ../react/src/query/use-query.ts
+// ../react/src/hooks/use-query.ts
 import { useEffect, useState } from "react";
 
 // ../react/src/world/use-world.ts
@@ -17,7 +17,7 @@ function useWorld() {
   return world;
 }
 
-// ../react/src/query/use-query.ts
+// ../react/src/hooks/use-query.ts
 function useQuery(...parameters) {
   const world = useWorld();
   const [entities, setEntities] = useState([]);
@@ -55,7 +55,7 @@ function createActions(actionSet) {
   );
 }
 
-// ../react/src/trait/use-observe.tsx
+// ../react/src/hooks/use-observe.ts
 import { useEffect as useEffect2, useState as useState2 } from "react";
 function useObserve(entity, trait) {
   const world = useWorld();
@@ -73,9 +73,29 @@ function useObserve(entity, trait) {
   }, [entity, trait]);
   return value;
 }
+
+// ../react/src/hooks/use-entity-ref.ts
+import { useCallback, useRef } from "react";
+function useEntityRef(callback) {
+  const world = useWorld();
+  const entityRef = useRef(null);
+  return useCallback(
+    (node) => {
+      if (node) {
+        if (entityRef.current) entityRef.current.destroy();
+        entityRef.current = world.spawn();
+        callback(node, entityRef.current);
+      } else if (entityRef.current) {
+        entityRef.current.destroy();
+      }
+    },
+    [world]
+  );
+}
 export {
   WorldProvider,
   createActions,
+  useEntityRef,
   useObserve,
   useQuery,
   useWorld

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koota",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "🌎 Performant data-oriented state management for React and TypeScript.",
   "license": "ISC",
   "type": "module",
@@ -9,18 +9,25 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
     "./react": {
-      "types": "./dist/react.d.ts",
+      "types": {
+        "import": "./dist/react.d.ts",
+        "require": "./dist/react.d.cts"
+      },
       "import": "./dist/react.js",
       "require": "./dist/react.cjs"
     }
   },
   "files": [
     "dist",
+    "react",
     "README.md",
     "LICENSE"
   ],
@@ -31,8 +38,8 @@
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "tsup": "^8.3.0",
-    "@koota/react": "0.0.1",
     "@koota/core": "0.0.1",
+    "@koota/react": "0.0.1",
     "tsconfig": "0.1.0"
   },
   "peerDependencies": {
@@ -53,7 +60,7 @@
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts src/react.ts --format esm,cjs --dts --dts-resolve && tsx scripts/copy-readme.ts",
+    "build": "tsup src/index.ts src/react.ts --format esm,cjs --dts --dts-resolve && tsx scripts/copy-readme.ts && tsx scripts/copy-react-files.ts",
     "test": "vitest --environment=jsdom"
   }
 }

package/react/index.cjs

@@ -0,0 +1,132 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react.ts
+var react_exports = {};
+__export(react_exports, {
+  WorldProvider: () => WorldProvider,
+  createActions: () => createActions,
+  useEntityRef: () => useEntityRef,
+  useObserve: () => useObserve,
+  useQuery: () => useQuery,
+  useWorld: () => useWorld
+});
+module.exports = __toCommonJS(react_exports);
+
+// ../react/src/hooks/use-query.ts
+var import_react3 = require("react");
+
+// ../react/src/world/use-world.ts
+var import_react2 = require("react");
+
+// ../react/src/world/world-context.ts
+var import_react = require("react");
+var WorldContext = (0, import_react.createContext)(null);
+
+// ../react/src/world/use-world.ts
+function useWorld() {
+  const world = (0, import_react2.useContext)(WorldContext);
+  if (!world) throw new Error("Koota ECS: Hooks can only be used within the World component!");
+  return world;
+}
+
+// ../react/src/hooks/use-query.ts
+function useQuery(...parameters) {
+  const world = useWorld();
+  const [entities, setEntities] = (0, import_react3.useState)([]);
+  (0, import_react3.useEffect)(() => {
+    const unsubAdd = world.onAdd(parameters, (entity) => {
+      setEntities((v) => [...v, entity]);
+    });
+    const unsubRemove = world.onRemove(parameters, (entity) => {
+      setEntities((v) => v.filter((e) => e !== entity));
+    });
+    return () => {
+      unsubAdd();
+      unsubRemove();
+    };
+  }, [world, parameters]);
+  return entities;
+}
+
+// ../react/src/world/world-provider.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function WorldProvider({ children, world }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(WorldContext.Provider, { value: world, children });
+}
+
+// ../react/src/actions/create-actions.ts
+function createActions(actionSet) {
+  return Object.assign(
+    () => {
+      const world = useWorld();
+      return actionSet(world);
+    },
+    {
+      get: (world) => actionSet(world)
+    }
+  );
+}
+
+// ../react/src/hooks/use-observe.ts
+var import_react4 = require("react");
+function useObserve(entity, trait) {
+  const world = useWorld();
+  const [value, setValue] = (0, import_react4.useState)(() => {
+    if (entity.has(trait)) return entity.get(trait);
+    return void 0;
+  });
+  (0, import_react4.useEffect)(() => {
+    const unsub = world.onChange(trait, (e) => {
+      if (e === entity) setValue(e.get(trait));
+    });
+    return () => {
+      unsub();
+    };
+  }, [entity, trait]);
+  return value;
+}
+
+// ../react/src/hooks/use-entity-ref.ts
+var import_react5 = require("react");
+function useEntityRef(callback) {
+  const world = useWorld();
+  const entityRef = (0, import_react5.useRef)(null);
+  return (0, import_react5.useCallback)(
+    (node) => {
+      if (node) {
+        if (entityRef.current) entityRef.current.destroy();
+        entityRef.current = world.spawn();
+        callback(node, entityRef.current);
+      } else if (entityRef.current) {
+        entityRef.current.destroy();
+      }
+    },
+    [world]
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WorldProvider,
+  createActions,
+  useEntityRef,
+  useObserve,
+  useQuery,
+  useWorld
+});

package/react/index.d.cts

@@ -0,0 +1,21 @@
+import { Q as QueryParameter, j as Entity, W as World, T as Trait, d as TraitInstanceFromSchema, E as ExtractSchema } from './world-BRz2NI5_.cjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+declare function useQuery(...parameters: QueryParameter[]): Entity[];
+
+declare function WorldProvider({ children, world }: {
+    children: React.ReactNode;
+    world: World;
+}): react_jsx_runtime.JSX.Element;
+
+declare function useWorld(): World;
+
+declare function createActions<T extends Record<string, (...args: any[]) => any>>(actionSet: (world: World) => T): (() => T) & {
+    get: (world: World) => T;
+};
+
+declare function useObserve<T extends Trait>(entity: Entity, trait: T): TraitInstanceFromSchema<ExtractSchema<T>> | undefined;
+
+declare function useEntityRef<T = any>(callback: (node: T, entity: Entity) => void): (node: T) => void;
+
+export { WorldProvider, createActions, useEntityRef, useObserve, useQuery, useWorld };

package/react/index.d.ts

@@ -0,0 +1,21 @@
+import { Q as QueryParameter, j as Entity, W as World, T as Trait, d as TraitInstanceFromSchema, E as ExtractSchema } from './world-BRz2NI5_.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+declare function useQuery(...parameters: QueryParameter[]): Entity[];
+
+declare function WorldProvider({ children, world }: {
+    children: React.ReactNode;
+    world: World;
+}): react_jsx_runtime.JSX.Element;
+
+declare function useWorld(): World;
+
+declare function createActions<T extends Record<string, (...args: any[]) => any>>(actionSet: (world: World) => T): (() => T) & {
+    get: (world: World) => T;
+};
+
+declare function useObserve<T extends Trait>(entity: Entity, trait: T): TraitInstanceFromSchema<ExtractSchema<T>> | undefined;
+
+declare function useEntityRef<T = any>(callback: (node: T, entity: Entity) => void): (node: T) => void;
+
+export { WorldProvider, createActions, useEntityRef, useObserve, useQuery, useWorld };

package/react/index.js

@@ -0,0 +1,102 @@
+import "./chunk-AQ5VUG5P.js";
+
+// ../react/src/hooks/use-query.ts
+import { useEffect, useState } from "react";
+
+// ../react/src/world/use-world.ts
+import { useContext } from "react";
+
+// ../react/src/world/world-context.ts
+import { createContext } from "react";
+var WorldContext = createContext(null);
+
+// ../react/src/world/use-world.ts
+function useWorld() {
+  const world = useContext(WorldContext);
+  if (!world) throw new Error("Koota ECS: Hooks can only be used within the World component!");
+  return world;
+}
+
+// ../react/src/hooks/use-query.ts
+function useQuery(...parameters) {
+  const world = useWorld();
+  const [entities, setEntities] = useState([]);
+  useEffect(() => {
+    const unsubAdd = world.onAdd(parameters, (entity) => {
+      setEntities((v) => [...v, entity]);
+    });
+    const unsubRemove = world.onRemove(parameters, (entity) => {
+      setEntities((v) => v.filter((e) => e !== entity));
+    });
+    return () => {
+      unsubAdd();
+      unsubRemove();
+    };
+  }, [world, parameters]);
+  return entities;
+}
+
+// ../react/src/world/world-provider.tsx
+import { jsx } from "react/jsx-runtime";
+function WorldProvider({ children, world }) {
+  return /* @__PURE__ */ jsx(WorldContext.Provider, { value: world, children });
+}
+
+// ../react/src/actions/create-actions.ts
+function createActions(actionSet) {
+  return Object.assign(
+    () => {
+      const world = useWorld();
+      return actionSet(world);
+    },
+    {
+      get: (world) => actionSet(world)
+    }
+  );
+}
+
+// ../react/src/hooks/use-observe.ts
+import { useEffect as useEffect2, useState as useState2 } from "react";
+function useObserve(entity, trait) {
+  const world = useWorld();
+  const [value, setValue] = useState2(() => {
+    if (entity.has(trait)) return entity.get(trait);
+    return void 0;
+  });
+  useEffect2(() => {
+    const unsub = world.onChange(trait, (e) => {
+      if (e === entity) setValue(e.get(trait));
+    });
+    return () => {
+      unsub();
+    };
+  }, [entity, trait]);
+  return value;
+}
+
+// ../react/src/hooks/use-entity-ref.ts
+import { useCallback, useRef } from "react";
+function useEntityRef(callback) {
+  const world = useWorld();
+  const entityRef = useRef(null);
+  return useCallback(
+    (node) => {
+      if (node) {
+        if (entityRef.current) entityRef.current.destroy();
+        entityRef.current = world.spawn();
+        callback(node, entityRef.current);
+      } else if (entityRef.current) {
+        entityRef.current.destroy();
+      }
+    },
+    [world]
+  );
+}
+export {
+  WorldProvider,
+  createActions,
+  useEntityRef,
+  useObserve,
+  useQuery,
+  useWorld
+};