strapi-orm

library1.2.7jsnpmunverified

Strapi ORM v1.2.7 is a TypeScript library that simplifies interacting with Strapi CMS by providing decorators to map API responses to classes and generating query parameters. It supports field mapping for components, relations, and custom mappers, as well as automatic relation population and entity fetching. The library is actively maintained but still early-stage (v1.x). Key differentiators include decorator-based mapping, built-in relation extraction, and an Entity class with fetch method. Alternative libraries like @strapi/strapi or custom fetch wrappers exist, but Strapi ORM offers a structured ORM-like approach.

database

npm install strapi-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · STRAPI-ORM

strapi-orm

databasejavascriptv1.2.7

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

field

✓ import { field } from 'strapi-orm';

✗ import { Field } from 'strapi-orm';

The decorator is exported as lower camelCase 'field', not 'Field'.

FieldType

✓ import { FieldType } from 'strapi-orm';

✗ import { FieldTypes, fieldType } from 'strapi-orm';

Exported as PascalCase 'FieldType' with values like FieldType.COMPONENT and FieldType.RELATION.

StrapiObject

✓ import { StrapiObject } from 'strapi-orm';

✗ import { StrapiObject } from 'strapi-orm/lib/core';

Main class is exported from root package.

Entity

✓ import { Entity } from 'strapi-orm';

Entity extends StrapiObject and adds fetch method.

getFlatRelationsForObject

✓ import { getFlatRelationsForObject } from 'strapi-orm/lib/util/relationUtil';

✗ import { getFlatRelationsForObject } from 'strapi-orm';

This utility is not exported from the root; must use the specific path. Path uses 'lib/util' which is internal.

createQuery

✓ import { createQuery } from 'strapi-orm/lib/query';

✗ import { createQuery } from 'strapi-orm';

Query function is not exported from root; uses the lib/query path.

Demonstrates class definition with decorators, relation extraction, entity fetching, and query building using Strapi ORM.

import { field, FieldType, Entity } from 'strapi-orm'; import { getFlatRelationsForObject } from 'strapi-orm/lib/util/relationUtil'; import { createQuery } from 'strapi-orm/lib/query'; // Define your Strapi objects class Relation extends Entity { @field() foo!: string; } class Home extends Entity { @field() baz!: string; @field(FieldType.RELATION, { builder: () => new Relation() }) relation!: Relation; } // Fetch all relations flat list const relations = getFlatRelationsForObject(new Home()); // relations -> ['relation'] // Fetch using Entity const strapiURL = 'http://localhost:1337/api'; const home = await new Home().fetch(`${strapiURL}/home`); console.log(home); // Home instance with mapped relation // Build query params const where = [{ value: '1', field: 'id', operator: 'eq' }]; const query = createQuery({ where, populate: relations.join(',') }); console.log(query); // array of [key, value] pairs

Debug

Known issues

gotchaUtility functions like getFlatRelationsForObject and createQuery are not exported from the root package; they require deep imports from 'strapi-orm/lib/util/relationUtil' and 'strapi-orm/lib/query' which are not documented and may change in minor versions.

fix

Use the documented deep import paths, but be aware they are internal and may break. Consider contributing to the library to officially export them.

affects: >=1.0.0

gotchaRelation property names must exactly match the Strapi API field names; otherwise mapping fails silently.

fix

Ensure that the property name in your class matches the attribute name in Strapi's response (case-sensitive).

affects: >=1.0.0

gotchaThe Entity.fetch method requires the full URL to the Strapi endpoint. It does not prepend a base URL, so you must pass the complete URL including protocol and host.

fix

Always pass full URL like `${strapiURL}/api/home`.

affects: >=1.0.0

gotchaThe library version 1.2.7 is early in development; API may change in minor versions. There is no stability guarantee.

fix

Pin dependency to exact version and test after upgrades.

affects: >=1.0.0 <2.0.0

Errors

Common errors & fixes

Cannot find module 'strapi-orm/lib/util/relationUtil'

Import path for utility functions is not part of the main package exports and may vary between versions.

fix

Check that you have the correct path. In v1.2.7, use 'strapi-orm/lib/util/relationUtil' exactly. Alternatively, open an issue to request official export.

TypeError: Class extends value undefined is not a constructor or null

Circular dependency or import order issue if StrapiObject or Entity is not imported correctly.

fix

Ensure 'import { StrapiObject } from 'strapi-orm'' is placed before any class that extends it.

Property 'fetch' does not exist on type 'Home'

Your class extends StrapiObject instead of Entity. fetch is only available on Entity.

fix

Change 'extends StrapiObject' to 'extends Entity' in your class definition.

Cannot read properties of undefined (reading 'src')

Trying to access property of a relation that was not populated or returned as null.

fix

Use optional chaining (?. ) when accessing nested relation properties, or ensure your Strapi API returns the expected data.

Upgrade

Version history

1.2.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node