Fix/optional table keys

[xinaesthete]

Fixes #46

Also changed some deprecated z.passthrough() to use looseObject and changed the API so that getTableKeys() is only a method of TableElement.

Summary by CodeRabbit

• New Features

  • Tables can now exist without being associated with spatial elements.
  • Enhanced table association APIs with improved key normalization and handling of missing metadata.

• Documentation

  • Expanded documentation for table association helpers, including usage patterns and API behavior.
  • Clarified how the system handles missing or null association metadata.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 57dd8b39-43ae-4c0f-be8d-1151a9efebd8

📥 Commits

Reviewing files that changed from the base of the PR and between 2e74bea and 4381502.

📒 Files selected for processing (9)

• .changeset/proud-candies-smell.md
• docs/docs/core/elements.mdx
• docs/docs/core/overview.mdx
• packages/core/src/models/index.ts
• packages/core/src/schemas/index.ts
• packages/core/src/store/index.ts
• packages/core/tests/schemas.spec.ts
• packages/core/tests/tableAssociations.spec.ts
• packages/layers/src/spatialLayerProps.ts

---

📝 Walkthrough

Walkthrough

This PR allows tables without spatial association metadata by making association fields optional/nullable in schemas, moving normalization logic into TableElement.getTableKeys(), and updating all integration points to handle missing association data gracefully. A minor release of @spatialdata/core documents the schema change.

Changes

Table Association Metadata Flexibility

Layer / File(s)	Summary
Schema relaxation for optional association metadata packages/core/src/schemas/index.ts, packages/core/tests/schemas.spec.ts	tableAttrsSchema makes instance_key, region, and region_key optional and nullable; multiple Zod schemas switch from .object(...).passthrough() to .looseObject(...) for consistent unknown-field handling. New test validates schema accepts null keys.
Normalization logic refactoring packages/core/src/models/index.ts	Remove standalone exported getTableKeys(input) helper; move normalization directly into TableElement.getTableKeys() with fallback logic returning empty region arrays and empty key strings when association metadata is missing/falsy.
Integration and test updates packages/core/src/store/index.ts, packages/core/tests/tableAssociations.spec.ts	SpatialData.getAssociatedTables calls table.getTableKeys() instead of imported helper; extend test fixtures with orphan_table and null_keys_table; add assertions for empty normalized keys and filtering out tables without region metadata.
Public API and user documentation docs/docs/core/elements.mdx, docs/docs/core/overview.mdx, .changeset/proud-candies-smell.md	Document normalized table-key workflow via getTableKeys(); update TableAttrs schema docs to reflect optional/nullable fields; expand public API list to include TableElement.getTableKeys() and SpatialData.getAssociatedTable(s) with normalization behavior; add minor release changelog.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• Taylor-CCB-Group/SpatialData.js#19: Introduces table-association helpers that are now refactored in this PR by removing the standalone exported getTableKeys helper and moving its normalization into the instance method.

Poem

A table once orphaned, now finds its way home,
No spatial links required, it's free now to roam.
Null keys and missing fields? No worries at all,
Normalization handles it, standing tall! 🐰
Flexibility blooms in the schema's design,
Where tables without anchors now gracefully shine. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'Fix/optional table keys' directly addresses the core change—making table association keys optional/nullable instead of required.
Linked Issues check	✅ Passed	The PR fully addresses issue #46 by making tableAttrsSchema optional/nullable [#46], restricting getTableKeys to TableElement method only [#46], and updating schema validation to handle absence properly [#46].
Out of Scope Changes check	✅ Passed	All changes are scoped to the linked issue: schema fixes, API restriction, documentation updates, and test additions directly support the objective of handling optional table association keys.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/optional_table_keys

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}