Strapi Deep Field

@antibusy/strapi-deep-field is a server library for Strapi >=5.0.0 <6.0.0. It registers no plugin, routes, permissions, or admin UI.

npm install @antibusy/strapi-deep-field

import { createDeepField, type DeepFieldService } from '@antibusy/strapi-deep-field';

const deepField: DeepFieldService = createDeepField({ strapi });
const fields = await deepField.listFields('api::contact.contact', {
  types: ['string', 'email'],
  includePrivate: false,
});

Create a service in the consuming plugin and pass its host Strapi instance. Metadata caches are isolated per Strapi instance and expire after one minute. Content Manager provides saved labels/main fields when available, with schema fallbacks otherwise. No browser runtime is provided; admin pages call endpoints owned by their consuming plugin.

Authorization

These utilities perform trusted server operations. getValue queries Document Service without an HTTP caller's permission context. The consuming workflow or endpoint must enforce collection, record, tenant, and field access and sanitize returned data. includePrivate: false excludes private/password attributes and all descendants beneath them during field discovery. Omitting it preserves the original plugin's internal discovery behavior. It is not an authorization check.

API Reference

Service Methods

listFields(collectionUid, options?)

List all mappable fields for a collection.

Options:

• types: Array of basic types to include (default: all types)
• includeRepeatable: Include fields in repeatable components (default: true)
• maxDepth: Maximum traversal depth (default: 3)
• customFieldUids: Array of custom field UIDs to include
• includeRelations: Include relation fields (default: true)
• componentCategories: Filter by component categories

Returns: MappableField[]

getValue(collectionUid, documentId, fieldPath, options?)

Get value from a field path in an entry (fetches the entry automatically).

Options:

• relationOutput: 'documentId' | 'mainField' | 'populate' (default: 'documentId')
• forEntryMutation: Prepare value for create/update operations

Returns: FieldValueResult

getValueFromEntry(entry, fieldPath, collectionUid, options?)

Get value from a field path in an already-fetched entry.

buildPopulateConfig(collectionUid, paths)

Build Strapi populate configuration for given field paths.

Returns: Record<string, any>

getMainField(collectionUid)

Get the main display field for a collection.

Returns: MainFieldInfo | null

getComponentInfo(componentUid)

Get information about a component.

Returns: ComponentInfo | null

validateFieldPath(collectionUid, fieldPath, expectedTypes?)

Validate if a field path is valid for a collection.

Returns: { valid: boolean; error?: string; field?: MappableField }

Field Path Notation

Use dot notation for nested fields:

• Simple field: firstName
• Component field: address.street
• Dynamic zone with component filter: identities[identity.line].uid
• Relation field: organization.name

Local development and release

Run npm ci, npm test, and npm pack. Parity tests use the published plugin 0.0.7 as a pinned development-only dependency. Version 0.1.0 is initially installed in Customer's consuming plugins using identical vendored tarballs. After publication, replace their relative file dependencies with the registry version and regenerate lockfiles. Publishing this library does not change the independent Deep Field plugin.

License

MIT