#SQLResource

Resource yang menjalankan query berdasarkan konfigurasi SQL yang sudah disimpan atau SQL dinamis, sumber data adalah API seperti flowSql:run / flowSql:runById. Cocok untuk skenario seperti laporan, statistik, list SQL kustom, dll. Berbeda dengan MultiRecordResource, SQLResource tidak bergantung pada data table, langsung mengeksekusi query SQL, mendukung pagination, parameter binding, variabel template ({{ctx.xxx}}), dan kontrol tipe hasil.

Hubungan Inheritance: FlowResource → APIResource → BaseRecordResource → SQLResource.

Cara Pembuatan: ctx.makeResource('SQLResource') atau ctx.initResource('SQLResource'). Saat dijalankan berdasarkan konfigurasi yang sudah disimpan perlu setFilterByTk(uid) (uid template SQL); saat debugging dapat menggunakan setDebug(true) + setSQL(sql) untuk langsung mengeksekusi SQL; di RunJS ctx.api disuntikkan oleh runtime environment.

#Skenario Penggunaan

#Format Data

• getData() mengembalikan format berbeda berdasarkan setSQLType():
  • selectRows (default): array, hasil multiple row
  • selectRow: objek tunggal
  • selectVar: nilai scalar (seperti COUNT, SUM)
• getMeta() mengembalikan informasi meta seperti pagination: page, pageSize, count, totalPage, dll.

#Konfigurasi SQL dan Mode Eksekusi

#Parameter dan Konteks

#Pagination

Di SQL dapat menggunakan {{ctx.limit}}, {{ctx.offset}} untuk mereferensikan parameter pagination, SQLResource akan menyuntikkan limit, offset di konteks.

#Pengambilan Data dan Event

#Contoh

#Eksekusi Berdasarkan Template yang Sudah Disimpan (runById)

ctx.initResource('SQLResource');
ctx.resource.setFilterByTk('active-users-report'); // uid template SQL yang sudah disimpan
ctx.resource.setBind({ status: 'active' });
await ctx.resource.refresh();
const data = ctx.resource.getData();
const meta = ctx.resource.getMeta(); // page, pageSize, count, dll.

#Mode Debug: Langsung Mengeksekusi SQL (runBySQL)

const res = ctx.makeResource('SQLResource');
res.setDebug(true);
res.setSQL('SELECT * FROM users WHERE status = :status LIMIT {{ctx.limit}}');
res.setBind({ status: 'active' });
await res.refresh();
const data = res.getData();

#Pagination dan Pindah Halaman

ctx.resource.setFilterByTk('user-list-sql');
ctx.resource.setPageSize(20);
await ctx.resource.refresh();

// Pindah halaman
await ctx.resource.next();
await ctx.resource.previous();
await ctx.resource.goto(3);

#Tipe Hasil

// Multiple row (default)
ctx.resource.setSQLType('selectRows');
const rows = ctx.resource.getData(); // [{...}, {...}]

// Single row
ctx.resource.setSQLType('selectRow');
const row = ctx.resource.getData(); // {...}

// Single value (seperti COUNT)
ctx.resource.setSQLType('selectVar');
const total = ctx.resource.getData(); // 42

#Menggunakan Variabel Template

ctx.defineProperty('minId', { get: () => 10 });
const res = ctx.makeResource('SQLResource');
res.setDebug(true);
res.setSQL('SELECT * FROM users WHERE id > {{ctx.minId}} LIMIT {{ctx.limit}}');
await res.refresh();

#Memantau Event refresh

ctx.resource?.on?.('refresh', () => {
  const data = ctx.resource.getData();
  ctx.render(<ul>{data?.map((r) => <li key={r.id}>{r.name}</li>)}</ul>);
});
await ctx.resource?.refresh?.();

#Hal yang Perlu Diperhatikan

• runById perlu menyimpan template terlebih dahulu: uid setFilterByTk(uid) harus merupakan ID template SQL yang sudah disimpan di management, dapat disimpan melalui ctx.sql.save({ uid, sql }).
• Mode debug perlu izin: saat setDebug(true) menjalankan flowSql:run, perlu role saat ini memiliki izin konfigurasi SQL; runById hanya perlu login.
• Debounce refresh: dalam event loop yang sama beberapa pemanggilan refresh() hanya akan mengeksekusi yang terakhir, untuk menghindari request berulang.
• Parameter binding mencegah injection: gunakan setBind() dengan placeholder :name / ?, untuk menghindari SQL injection akibat penggabungan string.

#Terkait

• ctx.sql - Eksekusi dan manajemen SQL, ctx.sql.runById cocok untuk query sekali pakai sederhana
• ctx.resource - Instance resource dalam konteks saat ini
• ctx.initResource() - Inisialisasi dan mengikat ke ctx.resource
• ctx.makeResource() - Membuat instance resource baru, tidak mengikat
• APIResource - API resource umum
• MultiRecordResource - Berorientasi data table/list