Skip to content
Slingshot

Overview

Human-owned documentation. This package owns search runtime behavior, not entity definition itself.

Purpose

Section titled “Purpose”

@lastshotlabs/slingshot-search turns entity-level search configuration into a live search runtime. It mounts search routes, initializes providers, discovers searchable entities from the framework’s entity registry, and keeps indexes in sync through post-setup event subscriptions.

Design Constraints

Section titled “Design Constraints”
  • Entity configuration is the source of truth. The package should discover entities with search config rather than requiring every searchable entity to be re-declared in plugin config.
  • Provider setup and route mounting belong in this package; entity authoring does not. Keep the boundary between slingshot-entity and slingshot-search explicit.
  • The package publishes runtime access through the SearchRuntimeCap capability after initialization. Cross-package consumers should resolve that capability via ctx.capabilities.require(SearchRuntimeCap) instead of reaching into search internals.

Built-in Strategies

Section titled “Built-in Strategies”

The search plugin supports built-in strategy strings for common cases:

  • tenantResolution: "framework" — reads tenant ID from the Hono context variable tenantId (set by framework tenancy middleware). Equivalent to tenantResolver: c => c.get('tenantId'). Requires tenantField to also be set.

  • adminGate: "superAdmin" — allows access to admin routes only for users with the super-admin role.

  • adminGate: "authenticated" — allows access to admin routes for any authenticated user (checks the request actor is not anonymous).

These strategy strings are resolved by the package at setup time. Pass functions directly when you need fully custom resolution.

Operational Notes

Section titled “Operational Notes”
  • adminGate is optional. Admin routes are only mounted when it is present.
  • If startup warns that the entity registry contains no searchable entities, the problem is usually missing entity config rather than provider failure.
  • Transform functions must be registered when the package is created. They are copied into the plugin’s internal registry before discovery and indexing begin.
  • Search sync is now registry-backed. When syncMode: "event-bus" is enabled, the package relies on canonical event definitions and ctx.events.publish(...) envelopes rather than legacy clientSafeEvents registration or raw bus payload assumptions.

Gotchas

Section titled “Gotchas”
  • setupMiddleware() is intentionally almost empty today. That is not dead code; it preserves room for future request-level search concerns without overloading route or post-setup phases.
  • setupPost() initializes indexes and wires event-sync subscriptions after entity discovery. If this phase is skipped in a custom integration, the routes may mount but the search runtime will not be complete.
  • mountPath must start with /; trailing slashes are trimmed before route mounting.
  • The package can target external providers or the DB-native provider. Docs should be careful not to imply one deployment shape when the package is designed to support several.
  • When syncMode: "event-bus" is used, failed flush operations (both index and delete) restore the affected documents to the pending queue so the next flush retries them. This means a transient provider outage does not cause silent data loss — documents accumulate in the pending queue and are retried on the next flush cycle. Documents indexed or deleted after the failure take precedence over the retry (non-overwriting restore).

Key Files

Section titled “Key Files”
  • src/plugin.ts
  • src/searchManager.ts
  • src/eventSync.ts
  • src/types/config.ts
  • src/testing.ts

Source-Backed Examples

Section titled “Source-Backed Examples”