Merge f6cac301db into 0046dcdf1a

assets/.github/ISSUE_TEMPLATE/BUG-REPORT.md

@@ -0,0 +1,22 @@
+---
+name: Bug report
+about: File a bug report for any behavior that you believe is unintentional or problematic
+title: "[BUG]"
+labels: bug
+assignees: ''
+
+---
+
+## Describe the bug
+Put a clear and concise description of what the bug is. This should be short and to the point, not to exceed more than a paragraph. Put the details inside your reproduction steps.
+
+## Reproduction
+Make an easy-to-follow guide on how to reproduce it. Does it happen all the time? Will specific features affect reproduction? All these questions should be answered for a good issue.
+
+This is a good place to put rbxl files or scripts that help explain your reproduction steps.
+
+## Expected Behavior
+What you expect to happen
+
+## Actual Behavior
+What actually happens

assets/.github/ISSUE_TEMPLATE/DOCUMENTATION.md

@@ -0,0 +1,14 @@
+---
+name: Documentation
+about: Open an issue to add, change, or otherwise modify any part of the documentation.
+title: "[DOCS]"
+labels: documentation
+assignees: ''
+
+---
+
+## Which Sections Does This Issue Cover?
+[Put sections (e.g. Query Concepts), page links, etc as necessary]
+
+## What Needs To Change?
+What specifically needs to change and what suggestions do you have to change it?

assets/.github/ISSUE_TEMPLATE/FEATURE-REQUEST.md

@@ -0,0 +1,27 @@
+---
+name: Feature Request
+about: File a feature request for something you believe should be added to Jecs
+title: "[FEATURE]"
+labels: enhancement
+assignees: ''
+
+---
+
+## Describe your Feature
+
+You should explain your feature here, and the motivation for why you want it.
+
+## Implementation
+
+Explain how you would implement your feature here. Provide relevant API examples and such here (if applicable).
+
+## Alternatives
+
+What other alternative implementations or otherwise relevant information is important to why you decided to go with this specific implementation?
+
+## Considerations
+
+Some questions that need to be answered include the following:
+- Will old code break in response to this feature?
+- What are the performance impacts with this feature (if any)?
+- How is it useful to include?

assets/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## Brief Description of your Changes.
+
+Describe what you did here. Additionally, you should link any relevant issues within this section. If there is no corresponding issue, you should include relevant information (repro steps, motivation, etc) here.
+
+## Impact of your Changes
+
+What implications will this have on the project? Will there be altered behavior or performance with this change?
+
+## Tests Performed
+
+What have you done to ensure this change has the least possible impact on the project?
+
+## Additional Comments
+
+Anything else you feel is relevant.

assets/.github/workflows/analysis.yaml

@@ -0,0 +1,19 @@
+name: analysis
+
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+    run:
+        name: Run Luau Analyze
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout Project
+              uses: actions/checkout@v4
+
+            - name: Install Luau
+              uses: encodedvenom/install-luau@v2.1
+
+            - name: Analyze
+              run: |
+                  output=$(luau-analyze src || true) # Suppress errors for now.

assets/.github/workflows/dependabot.yml

@@ -0,0 +1,11 @@
+---
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: "daily"

assets/.github/workflows/deploy-docs.yaml

@@ -0,0 +1,64 @@
+# Sample workflow for building and deploying a VitePress site to GitHub Pages
+#
+name: deploy-docs
+
+on:
+    # Runs on pushes targeting the `main` branch. Change this to `master` if you're
+    # using the `master` branch as the default branch.
+    push:
+        branches: [main]
+
+    # Allows you to run this workflow manually from the Actions tab
+    workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+    contents: read
+    pages: write
+    id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+    group: pages
+    cancel-in-progress: false
+
+jobs:
+    # Build job
+    build:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0 # Not needed if lastUpdated is not enabled
+            # - uses: pnpm/action-setup@v3 # Uncomment this if you're using pnpm
+            # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
+            - name: Setup Node
+              uses: actions/setup-node@v4
+              with:
+                  node-version: 20
+                  cache: npm # or pnpm / yarn
+            - name: Setup Pages
+              uses: actions/configure-pages@v4
+            - name: Install dependencies
+              run: npm ci # or pnpm install / yarn install / bun install
+            - name: Build with VitePress
+              run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
+            - name: Upload artifact
+              uses: actions/upload-pages-artifact@v3
+              with:
+                  path: docs/.vitepress/dist
+
+    # Deployment job
+    deploy:
+        environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+        needs: build
+        runs-on: ubuntu-latest
+        name: Deploy
+        steps:
+            - name: Deploy to GitHub Pages
+              id: deployment
+              uses: actions/deploy-pages@v4

assets/.github/workflows/publish-npm.yml

@@ -0,0 +1,17 @@
+name: publish-npm
+
+on:
+    push:
+        branches: [main]
+
+jobs:
+    publish:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v3
+              with:
+                  node-version: "20"
+            - uses: JS-DevTools/npm-publish@v3
+              with:
+                  token: ${{ secrets.NPM_AUTH_TOKEN }}

assets/.github/workflows/release.yaml

@@ -0,0 +1,71 @@
+name: release
+
+on:
+    push:
+        tags: ["v*"]
+
+jobs:
+    build:
+        name: Build
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout Project
+              uses: actions/checkout@v4
+
+            - name: Install Rokit
+              uses: CompeyDev/setup-rokit@v0.1.2
+
+            - name: Install Dependencies
+              run: wally install
+
+            - name: Build
+              run: rojo build --output build.rbxm default.project.json
+
+            - name: Upload Build Artifact
+              uses: actions/upload-artifact@v3
+              with:
+                  name: build
+                  path: build.rbxm
+
+    release:
+        name: Release
+        needs: [build]
+        runs-on: ubuntu-latest
+        permissions:
+            contents: write
+        steps:
+            - name: Checkout Project
+              uses: actions/checkout@v4
+
+            - name: Download Jecs Build
+              uses: actions/download-artifact@v3
+              with:
+                  name: build
+                  path: build
+
+            - name: Rename Build
+              run: mv build/build.rbxm jecs.rbxm
+
+            - name: Create Release
+              uses: softprops/action-gh-release@v1
+              with:
+                  name: Jecs ${{ github.ref_name }}
+                  files: |
+                      jecs.rbxm
+
+    publish:
+        name: Publish
+        needs: [release]
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout Project
+              uses: actions/checkout@v4
+
+            - name: Install Rokit
+              uses: CompeyDev/setup-rokit@v0.1.2
+
+            - name: Wally Login
+              run: wally login --token ${{ secrets.WALLY_AUTH_TOKEN }}
+
+            - name: Publish
+              run: wally publish

assets/.github/workflows/unit-testing.yaml

@@ -0,0 +1,31 @@
+name: unit-testing
+
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+    run:
+        name: Run Luau Tests
+        runs-on: ubuntu-latest
+        timeout-minutes: 2
+
+        steps:
+            - name: Checkout Project
+              uses: actions/checkout@v4
+
+            - name: Install Luau
+              uses: encodedvenom/install-luau@v4.3
+              with:
+                  version: "latest"
+                  verbose: "true"
+
+            - name: Run Unit Tests
+              id: run_tests
+              run: |
+                  output=$(luau test/tests.luau)
+                  echo "$output"
+                  if [[ "$output" == *"0 fails"* ]]; then
+                    echo "Unit Tests Passed"
+                  else
+                    echo "Error: One or More Unit Tests Failed."
+                    exit 1
+                  fi

docs/.vitepress/config.mts

@@ -1,65 +1,69 @@
-import { defineConfig } from "vitepress";
-
-// https://vitepress.dev/reference/site-config
-export default defineConfig({
-	title: "Jecs",
-	base: "/jecs/",
-	description: "A VitePress Site",
-	themeConfig: {
-		// https://vitepress.dev/reference/default-theme-config
-		nav: [
-			{ text: "Learn", link: "/" },
-			{ text: "API", link: "/api/jecs.md" },
-			{ text: "Examples", link: "https://github.com/Ukendio/jecs/tree/main/examples" },
-			{ text: "Coverage", link: "/coverage/index.html" },
-		],
-
-		sidebar: {
-			"/api/": [
-				{
-					text: "API reference",
-					items: [
-						{ text: "jecs", link: "/api/jecs" },
-						{ text: "World", link: "/api/world" },
-						{ text: "Query", link: "/api/query" },
-					],
-				},
-			],
-			"/learn/": [
-				{
-					text: "Introduction",
-					items: [
-						{ text: "Getting Started", link: "/learn/overview/get-started" },
-						{ text: "First Jecs Project", link: "/learn/overview/first-jecs-project" },
-					],
-				},
-				{
-					text: "Concepts",
-					items: [
-						{ text: "Entities and Components", link: "/learn/concepts/entities-and-components" },
-						{ text: "Queries", link: "/learn/concepts/queries" },
-						{ text: "Relationships", link: "/learn/concepts/relationships" },
-						{ text: "Component Traits", link: "learn/concepts/component-traits" },
-						{ text: "Addons", link: "/learn/concepts/addons" },
-					],
-				},
-				{
-					text: "FAQ",
-					items: [{ text: "How can I contribute?", link: "/learn/faq/contributing" }],
-				},
-			],
-			"/contributing/": [
-				{
-					text: "Contributing",
-					items: [
-						{ text: "Contribution Guidelines", link: "/learn/contributing/guidelines" },
-						{ text: "Submitting Issues", link: "/learn/contributing/issues" },
-						{ text: "Submitting Pull Requests", link: "/learn/contributing/pull-requests" },
-					],
-				},
-			],
-		},
-
-		socialLinks: [{ icon: "github", link: "https://github.com/ukendio/jecs" }],
-	},
-});
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+    title: "Jecs",
+    base: "/jecs/",
+    description: "A VitePress Site",
+    themeConfig: {
+        // https://vitepress.dev/reference/default-theme-config
+        nav: [
+            { text: 'Learn', link: '/' },
+            { text: 'API', link: '/api/jecs.md' },
+            { text: 'Examples', link: 'https://github.com/Ukendio/jecs/tree/main/examples' },
+        ],
+
+        sidebar: {
+            "/api/": [
+                {
+                    text: "API reference",
+                    items: [
+                        { text: "jecs", link: "/api/jecs" },
+                        { text: "World", link: "/api/world" },
+                        { text: "Query", link: "/api/query" }
+                    ]
+                }
+            ],
+            "/learn/": [
+                {
+                    text: "Introduction",
+                    items: [
+                        { text: 'Getting Started', link: '/learn/overview/get-started' },
+                        { text: 'First Jecs Project', link: '/learn/overview/first-jecs-project' }
+                    ]
+                },
+                {
+                    text: 'Concepts',
+                    items: [
+                        { text: 'Entities and Components', link: '/learn/concepts/entities-and-components' },
+                        { text: 'Queries', link: '/learn/concepts/queries' },
+                        { text: 'Relationships', link: '/learn/concepts/relationships' },
+                        { text: 'Component Traits', link: 'learn/concepts/component-traits' },
+                        { text: 'Addons', link: '/learn/concepts/addons' }
+                    ]
+                },
+                {
+                    text: "FAQ",
+                    items: [
+                        { text: 'How can I contribute?', link: '/learn/faq/contributing' }
+                    ]
+                },
+
+            ],
+            "/contributing/": [
+                {
+                    text: 'Contributing',
+                    items: [
+                        { text: 'Contribution Guidelines', link: '/learn/contributing/guidelines' },
+                        { text: 'Submitting Issues', link: '/learn/contributing/issues' },
+                        { text: 'Submitting Pull Requests', link: '/learn/contributing/pull-requests' },
+                    ]
+                }
+            ]
+        },
+
+        socialLinks: [
+            { icon: 'github', link: 'https://github.com/ukendio/jecs' }
+        ]
+    }
+})

docs/api/jecs.md

@@ -45,6 +45,6 @@ function jecs.pair(
 ```
 ::: info
 
-While relationship pairs can be used as components and have data associated with an ID, they cannot be used as entities. Meaning you cannot add components to a pair as the source of a binding.
+Note that while relationship pairs can be used as components, meaning you can add data with it as an ID, however they cannot be used as entities. Meaning you cannot add components to a pair as the source of a binding.
 
 :::

tools/testkit.luau

@@ -112,7 +112,6 @@ type Test = {
 		trace: string,
 	}?,
 	focus: boolean,
-	fn: () -> ()
 }
 
 type Case = {
@@ -232,9 +231,7 @@ local function TEST(name: string, fn: () -> ())
 		fn = fn
 	}
 
-	local t = test
-
-	table.insert(tests, t)
+	table.insert(tests, test)
 end
 
 local function FOCUS()
@@ -261,22 +258,22 @@ local function FINISH(): boolean
 			continue
 		end
 		test = t
-		local fn = t.fn
+		fn = t.fn
 		local start = os.clock()
 		local err
-		local ok = xpcall(fn, function(m: string)
+		local success = xpcall(fn, function(m: string)
 			err = { message = m, trace = debug.traceback(nil, 2) }
 		end)
-		t.duration = os.clock() - start
+		test.duration = os.clock() - start
 
-		if not t.case then
+		if not test.case then
 			CASE("")
 		end
-		assert(t.case, "no active case")
+		assert(test.case, "no active case")
 
-		if not ok then
-			t.case.result = ERROR
-			t.error = err
+		if not success then
+			test.case.result = ERROR
+			test.error = err
 		end
 		collectgarbage()
 	end